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:

Download and install the Postman from https://www.getpostman.com. Fire it up!
Make sure Http method is set to POST.
Enter the URL (refer to subsequent pages in this document) in the field request URL.
Enter your API Key under Headers.
Enter the message details under Body.
Click on the Send button.

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.

S. No	API Name	Description	Platform
1	OC.user.getSessionID	Get user active session ID
2	OC.user.deviceInfo	Get current device model number and screen size
3	OC.user.getVCard	Get user vCard
4	OC.user.selectContacts	Shows OneChat contacts selector
5	OC.message.single.relay	To share / broadcast message to single chat
6	OC.message.group.relay	To share / broadcast message to group chat
7	registerMiniApp	Register new mini app	Server
8	authenticateUser	Authenticate user session ID	Server

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