OneChat - API

Publish date: 2024-05-02

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
    BodyNameMandatoryDescriptionSample
    domainYesDomain to be broadcastedonechat.net
    messageYesMessage to be broadcastedHi
    HeadersapikeyYesThis is the consumer key of the approved App created in the Developer Portal.j4w4tty4Lw80hAbAHQGKwto
    Response Details
    AttributesDescriptionSample
    statusStatusSuccess, Error
    descriptionDescription 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
    BodyNameMandatoryDescriptionSample
    jidYesThe jid of the specific user6581234567@onechat.net
    messageYesMessage to be broadcastedHi
    HeadersapikeyYesThis is the consumer key of the approved App created in the Developer Portal.j4w4tty4Lw80hAbAHBDKwto
    Response Details
    AttributesDescriptionSample
    statusStatusSuccess, Error
    descriptionDescription 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
    BodyNameMandatoryDescriptionSample
    jidYesThe jid of the specific groupabcdef-123456@muc.onechat.net
    messageYesMessage to be broadcastedHi
    HeadersapikeyYesThis is the consumer key of the approved App created in the Developer Portal.j4w4tty4Lw80hAbAHBDKwto
    Response Details
    AttributesDescriptionSample
    statusStatusSuccess, Error
    descriptionDescription 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. NoAPI NameDescription
    1init functionInitializes the app, typically on document ready.
    2login functionLogin to OneChat server
    3logout functionLogout
    4createNewGroupChat functionCreates a group chat
    5getConnectionStatus functionGet current connection status
    6subscribeConnectionStatus functionSubscribe to connection status
    7unsubscribeConnectionStatus functionUnsubscribe to connection status
    8VERSION variableReturns plugin version
    9BUILD_DATE variableReturns plugin build date
    init function
    Namespaceocwp
    DescriptionInitializes the app, typically when the webpage has been fully loaded.
    Function
     ocwp.init({  prop: value, }); 
    Object props
    NameMandatoryTypeDefault ValueDescription
    confPathNoString‘config/‘Path to config folder, ends with trailing slash
    localeNoObjectpath: ‘locale/‘,
    default: ‘enGB’,
    Path to locale folder, ends with trailing slash
    containerElementYesElementContainer element where plugin will be rendered
    chatBoxNoObjectmarginLeft: 5,
    marginRight: 5,
    maxHeight: 600,
    maxWidth: 600,
    minHeight: 100,
    minWidth: 250,
    paddingTop: 80,
    outerPaddingLeft: '350px',
    outerPaddingRight: 0,
    Customising chat box appearances
    loginNoObjectProvide 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
    Namespaceocwp
    DescriptionInvokes login from webpage’s javascript code.
    Function
     ocwp.login(usr: string, pw: string); 
    Parameters
    NameMandatoryTypeDefault ValueDescription
    usrYesStringUsername / jid
    pwYesStringPassword

    Example

     ocwp.login(‘user@domain.com’, ‘your-password-goes-here’); 
    logout function
    Namespaceocwp
    DescriptionInvokes logout from webpage’s javascript code.
    Function
     ocwp.logout(); 

    Example

     ocwp.logout(); 
    createNewGroupChat function
    Namespaceocwp
    DescriptionCreates a group chat.
    Function
     ocwp.chat.group.create({  prop: value, }); 
    Parameters
    NameMandatoryTypeDefault ValueDescription
    membersYesArrayArray of members to be added to group, have to be at least 1 person, creator doesn't need to be included and not counted
    chatNameNoStringName of chat, optional, will use generic name if empty (configure in the locale .json)
    chatAvatarNoStringPath to image or base64 string, optional, will use default group avatar if empty
    chatJidNoStringuuid 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
    Namespaceocwp
    DescriptionGet xmpp messaging protocol connection status.
    Function
     ocwp.getConnectionStatus(); 
    ReturnsOne 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
    Namespaceocwp
    DescriptionSubscribe 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
    Namespaceocwp
    DescriptionUnsubscribe to previously subscribed xmpp messaging protocol status.
    Function
     ocwp.unsubscribeConnectionStatus(); 

    Example

     ocwp.unsubscribeConnectionStatus(); 
    VERSION variable
    Namespaceocwp
    DescriptionReturns current version of OneChat Messaging Library plugin.
    Var
     ocwp.VERSION 

    Example

     ocwp.VERSION  // 4474 
    BUILD_DATE variable
    Namespaceocwp
    DescriptionReturns 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
    NamespaceOC
    DescriptionGet 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
    NamespaceOC
    DescriptionGet 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
    NamespaceOC
    DescriptionGet 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
    NamespaceOC
    DescriptionShows 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
    NamespaceOC
    DescriptionTo 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
    NamespaceOC
    DescriptionTo 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
    BodyNameMandatoryDescriptionSample
    adminJidYesAdmin Username
    sessionIdYesSession ID
    appNameYesMini App Name
    appIconYesMini App Icon
    appUrlYesMini App URL
    Response Details
    AttributesDescriptionSample
    statusStatusSuccess, Error
    descriptionDescription of the status-, Unauthorized
    appIdApplication ID
    apiKeyapiKey for API calls
    authenticateUser

    URL: https://app.onechat.net/onechat/api/registerMiniApp

    Description: Authenticate user session ID for Mini App Server

    Request Details
    BodyNameMandatoryDescriptionSample
    jidYesUsername
    sessionIdYesSession ID
    appIdYesApplication ID
    apiKeyYesapiKey for API calls
    Response Details
    AttributesDescriptionSample
    statusStatusSuccess, Error
    descriptionDescription of the status-, Unauthorized
    isAuthenticatedReturns user validityTrue, False

    ncG1vNJzZmirY2KusXnSqKytoJWWwLV5kGeYppmqpLuiw9JnmqilX6S7pq%2FHmqtmr5WXfKK8yGefraWc