OneChat - API
Guide to make API call
API calls need to be made programmatically in regular intervals to obtain the constant stream of data for your respective development or research needs. For illustration purposes, the API call below is being made via a third-party application – Postman.
Steps to making an API call:
The figure below shows the JSON response of an API call made for particulars by name API.
Mass broadcast API
URL: https://app.onechat.net/onechat/api/massBroadcast
Description: Allows admin/system to mass broadcast to every user in the specific domain
Request Details | ||||
---|---|---|---|---|
Body | Name | Mandatory | Description | Sample |
domain | Yes | Domain to be broadcasted | onechat.net | |
message | Yes | Message to be broadcasted | Hi | |
Headers | apikey | Yes | This is the consumer key of the approved App created in the Developer Portal. | j4w4tty4Lw80hAbAHQGKwto |
Response Details | ||||
---|---|---|---|---|
Attributes | Description | Sample | ||
status | Status | Success, Error | ||
description | Description of the status | -, Unauthorized |
1-2-1 alert message relay API
URL: https://app.onechat.net/onechat/api/singleMessage
Description: Allows admin/system to send message to a particular user
Request Details | ||||
---|---|---|---|---|
Body | Name | Mandatory | Description | Sample |
jid | Yes | The jid of the specific user | 6581234567@onechat.net | |
message | Yes | Message to be broadcasted | Hi | |
Headers | apikey | Yes | This is the consumer key of the approved App created in the Developer Portal. | j4w4tty4Lw80hAbAHBDKwto |
Response Details | ||||
---|---|---|---|---|
Attributes | Description | Sample | ||
status | Status | Success, Error | ||
description | Description of the status | -, Unauthorized |
Group alert message relay API
URL: https://app.onechat.net/onechat/api/groupMessage
Description: Allows admin/system to send message to a particular group
Request Details | ||||
---|---|---|---|---|
Body | Name | Mandatory | Description | Sample |
jid | Yes | The jid of the specific group | abcdef-123456@muc.onechat.net | |
message | Yes | Message to be broadcasted | Hi | |
Headers | apikey | Yes | This is the consumer key of the approved App created in the Developer Portal. | j4w4tty4Lw80hAbAHBDKwto |
Response Details | ||||
---|---|---|---|---|
Attributes | Description | Sample | ||
status | Status | Success, Error | ||
description | Description of the status | -, Unauthorized |
Chat Plugin Javascript Library Functions
The below documentation refers to the OneChat Javascript library based functions and variables which can be plugged into any website to give it OneChat messaging capabilities.
S. No | API Name | Description |
---|---|---|
1 | init function | Initializes the app, typically on document ready. |
2 | login function | Login to OneChat server |
3 | logout function | Logout |
4 | createNewGroupChat function | Creates a group chat |
5 | getConnectionStatus function | Get current connection status |
6 | subscribeConnectionStatus function | Subscribe to connection status |
7 | unsubscribeConnectionStatus function | Unsubscribe to connection status |
8 | VERSION variable | Returns plugin version |
9 | BUILD_DATE variable | Returns plugin build date |
init function
Namespace | ocwp |
---|---|
Description | Initializes the app, typically when the webpage has been fully loaded. |
Function | ocwp.init({ prop: value, }); |
Object props | ||||
---|---|---|---|---|
Name | Mandatory | Type | Default Value | Description |
confPath | No | String | ‘config/‘ | Path to config folder, ends with trailing slash |
locale | No | Object | path: ‘locale/‘, default: ‘enGB’, | Path to locale folder, ends with trailing slash |
containerElement | Yes | Element | Container element where plugin will be rendered | |
chatBox | No | Object | marginLeft: 5, marginRight: 5, maxHeight: 600, maxWidth: 600, minHeight: 100, minWidth: 250, paddingTop: 80, outerPaddingLeft: '350px', outerPaddingRight: 0, | Customising chat box appearances |
login | No | Object | Provide credentials if intend to login upon init |
Example
ocwp.init({ confPath: './config/', locale: { path: './locale/', default: 'enGB', // loading enGB.json as default }, containerElement: document.getElementById('onechatContainer'), chatbox: { marginLeft: 5, // margins between chat box marginRight: 5, // margins between chat box maxHeight: 600, maxWidth: 600, minHeight: 100, // default height when open minWidth: 250, // default width when open paddingTop: 80, outerPaddingLeft: '350px', // padding on the left, set the width of the left bar here to prevent open chat boxes from covering the bar outerPaddingRight: 0, // padding on right }, // LOGIN ON INIT login: { usr: 'jid', pw: 'password', }, });
login function
Namespace | ocwp |
---|---|
Description | Invokes login from webpage’s javascript code. |
Function | ocwp.login(usr: string, pw: string); |
Parameters | ||||
---|---|---|---|---|
Name | Mandatory | Type | Default Value | Description |
usr | Yes | String | Username / jid | |
pw | Yes | String | Password |
Example
ocwp.login(‘user@domain.com’, ‘your-password-goes-here’);
logout function
Namespace | ocwp |
---|---|
Description | Invokes logout from webpage’s javascript code. |
Function | ocwp.logout(); |
Example
ocwp.logout();
createNewGroupChat function
Namespace | ocwp |
---|---|
Description | Creates a group chat. |
Function | ocwp.chat.group.create({ prop: value, }); |
Parameters | ||||
---|---|---|---|---|
Name | Mandatory | Type | Default Value | Description |
members | Yes | Array | Array of members to be added to group, have to be at least 1 person, creator doesn't need to be included and not counted | |
chatName | No | String | Name of chat, optional, will use generic name if empty (configure in the locale .json) | |
chatAvatar | No | String | Path to image or base64 string, optional, will use default group avatar if empty | |
chatJid | No | String | uuid formatted string to id the group (please use a standard uuid), optional, will auto generate if empty, if group id exist, opens the groupchat |
Example
ocwp.chat.group.create({ members: ['memberjid1@domain', ...], chatName: 'Name of chat’, chatAvatar: 'path/to/image.jpg', chatJid: 'xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx', });
getConnectionStatus function
Namespace | ocwp |
---|---|
Description | Get xmpp messaging protocol connection status. |
Function | ocwp.getConnectionStatus(); |
Returns | One of below: XMPP_CONNECTION_IDLE XMPP_CONNECTION_DISCONNECTED XMPP_CONNECTION_CONNECTED XMPP_CONNECTION_CONNECTED_READY XMPP_CONNECTION_CONNECTING XMPP_CONNECTION_AUTHFAIL XMPP_CONNECTION_CONNFAIL XMPP_CONNECTION_ERROR |
Example
ocwp.getConnectionStatus(); // “XMPP_CONNECTION_IDLE"
subscribeConnectionStatus function
Namespace | ocwp |
---|---|
Description | Subscribe to xmpp messaging protocol connection status. When connection status changes, callback will be invoked with new status as callback parameter. |
Function | ocwp.subscribeConnectionStatus(callback :Function); |
Example
function onConnectionStatusChanged (status) { if (status == ‘XMPP_CONNECTION_DISCONNECTED’) { ocwp.login(jid, pw); } } ocwp.subscribeConnectionStatus(onConnectionStatusChanged);
unsubscribeConnectionStatus function
Namespace | ocwp |
---|---|
Description | Unsubscribe to previously subscribed xmpp messaging protocol status. |
Function | ocwp.unsubscribeConnectionStatus(); |
Example
ocwp.unsubscribeConnectionStatus();
VERSION variable
Namespace | ocwp |
---|---|
Description | Returns current version of OneChat Messaging Library plugin. |
Var | ocwp.VERSION |
Example
ocwp.VERSION // 4474
BUILD_DATE variable
Namespace | ocwp |
---|---|
Description | Returns build date of OneChat Messaging Library plugin. |
Var | ocwp.BUILD_DATE |
Example
ocwp.BUILD_DATE // 20180619
Mini App Library Functions
The below documentation refers to the OneChat Javascript library based functions and variables which can be used to integrate it with OneChat as a Mini App.
OC.user.getSessionID
Namespace | OC |
---|---|
Description | Get user active session ID. |
Function | OC.user.getSessionID(); |
Example
// JavaScript // on DOMContentLoaded document.addEventListener("DOMContentLoaded", function(event) { const sessionId = OC.user.getSessionID(); console.log(sessionId); });
OC.user.deviceInfo
Namespace | OC |
---|---|
Description | Get current device model number and screen size. |
Function | OC.user.deviceInfo(); |
Example
// JavaScript document.addEventListener("DOMContentLoaded", function(event) { const deviceInfo = OC.user.deviceInfo(); console.log(deviceInfo); // '{"device":"iPhone 7","os":"iOS 11.0","screenWidth":"","screenHeight":""}' });
OC.user.getVCard
Namespace | OC |
---|---|
Description | Get user vCard. |
Function | OC.user.getVCard(); |
Example
// JavaScript document.addEventListener("DOMContentLoaded", function(event) { const vCard = OC.user.getVCard(); console.log(vCard); // '{"jid":"user@domain.tld","userName":"Your username","avatar":"data:image/png;base64,/9j/4AAQSkZJRgABAQAASABIAAD..."}' });
OC.user.selectContacts
Namespace | OC |
---|---|
Description | Shows OneChat contacts selector. |
Function | OC.user.selectContacts({ success: function(selected) { }, maxNumberOfSelection: 1, }); |
Example
document.addEventListener("DOMContentLoaded", function(event) { // selectContacts({ success, maxNumberOfSelection }); // maxNumberOfSelection (optional): 1, 2, 3..., -1 for unlimited (default) OC.user.selectContacts({ success: function(selected) { console.log(selected); // 2 contacts selected // '["user1@domain.tld","user2@domain.tld"]' // or canceled // '[]' if (selected.length > 0) { // do things } }, maxNumberOfSelection: 1, }); });
OC.message.single.relay
Namespace | OC |
---|---|
Description | To share / broadcast message to single chat. |
Function | OC.message.single.relay({ recipient: '["user1@domain.tld","user2@domain.tld"]', textMessage: 'hello friend', success: function() { }, fail: function(err) { console.log(err); }, }); |
Example
document.addEventListener("DOMContentLoaded", function(event) { // retrieve an array of users from selectContacts // message will be sent to each of the user(s) in the array of contacts // recipient and textMessage are mandatory OC.message.single.relay({ recipient: '["user1@domain.tld","user2@domain.tld"]', textMessage: 'hello friend', success: function() { // all message sent successfully }, fail: function(err) { // Ops, handles fail accordingly console.log(err); }, }); });
OC.message.group.relay
Namespace | OC |
---|---|
Description | To share / broadcast message to group chat. |
Function | OC.message.group.relay({ groupJid: 'group-jid@domain.tld', invitees: '["user1@domain.tld","user2@domain.tld"]', textMessage: 'hello group', success: function(newGroupJidCreated) { }, fail: function(err) { console.log(err); }, }); |
Example
document.addEventListener("DOMContentLoaded", function(event) { // retrieved a array of users from selectContacts (optional, if group is provided) // groupJid (optional): new group will be created with invitees as members if not defined // invitees (optional): array of users, will be ignored if groupJid is given // message will be send to the group chat // ONE of groupJid or invitees must be provided, textMessage is mandatory OC.message.group.relay({ groupJid: 'group-jid@domain.tld', invitees: '["user1@domain.tld","user2@domain.tld"]', textMessage: 'hello group', success: function(newGroupJidCreated) { // message sent successfully // if groupJid wasn’t provided, a new group will be automatically created and group jid returned here, store this value to send updates to this group }, fail: function(err) { // Ops, handles fail accordingly console.log(err); }, }); });
registerMiniApp
URL: https://app.onechat.net/onechat/api/registerMiniApp
Description: Register new mini app in OneChat Admin Portal
Request Details | ||||
---|---|---|---|---|
Body | Name | Mandatory | Description | Sample |
adminJid | Yes | Admin Username | ||
sessionId | Yes | Session ID | ||
appName | Yes | Mini App Name | ||
appIcon | Yes | Mini App Icon | ||
appUrl | Yes | Mini App URL |
Response Details | ||
---|---|---|
Attributes | Description | Sample |
status | Status | Success, Error |
description | Description of the status | -, Unauthorized |
appId | Application ID | |
apiKey | apiKey for API calls |
authenticateUser
URL: https://app.onechat.net/onechat/api/registerMiniApp
Description: Authenticate user session ID for Mini App Server
Request Details | ||||
---|---|---|---|---|
Body | Name | Mandatory | Description | Sample |
jid | Yes | Username | ||
sessionId | Yes | Session ID | ||
appId | Yes | Application ID | ||
apiKey | Yes | apiKey for API calls |
Response Details | ||
---|---|---|
Attributes | Description | Sample |
status | Status | Success, Error |
description | Description of the status | -, Unauthorized |
isAuthenticated | Returns user validity | True, False |
ncG1vNJzZmirY2KusXnSqKytoJWWwLV5kGeYppmqpLuiw9JnmqilX6S7pq%2FHmqtmr5WXfKK8yGefraWc