Acrobits Turnkey Messaging Integration Requirements¶

This document describes the requirements for integrating the Acrobits Turnkey Messaging service into a CloudSoftphone or CloudSoftphone White Label application.

There are several requirements that need to be met in order to integrate the messaging service into the application:

Allowlist important IPs - please review our IP allowlist for Acrobits and CloudSoftphone services.

External Authentication endpoint - an external authentication endpoint is required to authorize users to use the messaging service.

Contact list requirements - a modified contact source is required for the messaging service to operate.

External Provisioning requirements - for multi tenant applications, the external provisioning endpoint is required to provide the Network ID for the user.

Enable iOS notification extension - Turnkey Messaging requires the iOS application to use the notification extension to display and localize notifications.

A more detailed description of the requirements follows.

External Authentication endpoint¶

External authentication endpoint is required in order to authorize users to use the messaging service. The external authentication is called by the Acrobits SSO server which then issues access tokens to the client applications.

Please refer to External Authentication page for more information.

Contact list requirements¶

A modified contact source is required for the messaging service to operate. The contact source is used to provide a list of messaging contacts that the user can send messages to. The contact source may contain both contacts that are to be used for messaging and also contacts that are to be used with other services (e.g. numbers on PSTN). When creating a new chat, the user will only be able to select contacts that are marked as messaging contacts.

For the messaging service to work, each contact entry for use in the messaging service must contain two identifiers:

Cloud Username - a unique identifier of the user that the contact represents. Cloud Username is typically the identifier that the user represented by the contact uses to log in. In case the SIP username is used as log in username, the SIP username should be supplied as the Cloud Username.

Network ID - identifier of the subnetwork (or subdomain) that the user belongs to. Network ID is used to separate users of different subnetworks in multi-tenant applications, but it is also required in contacts for single tenant applications.

Note

All contacts that are to be used for messaging must have the Cloud Username and Network ID fields set.

Warning

The Network ID information on a contact entry must match the Network ID provided by the external provisioning endpoint, see External Provisioning requirements.

The messaging contact list can be currently provided as a Web Service Contacts source or a CardDAV contact source.

An example web service contact source response including the Cloud Username and Network ID of users follows:

{
    "contacts": [
        {
            "contactId": "1",
            "cloudUsername": "john.doe",
            "networkId": "myNetwork",
            "displayName": "John Doe",
            "lname": "Doe",
            "fname": "John",
            "avatar" : "https://example.com/avatar.png",
            "largeAvatar" : "https://example.com/largeAvatar.png",
            "contactEntries": [
                {
                    "entryId": "tel:0",
                    "label": "work",
                    "type": "tel",
                    "uri": "1000"
                }
            ]
        },
        {
            "contactId": "2",
            "cloudUsername": "foo.bar",
            "networkId": "myNetwork",
            "displayName": "Foo Bar",
            "lname": "Bar",
            "fname": "Foo",
            "avatar" : "https://example.com/avatar.png",
            "largeAvatar" : "https://example.com/largeAvatar.png",
            "contactEntries": [
                {
                    "entryId": "tel:0",
                    "label": "work",
                    "type": "tel",
                    "uri": "1001"
                }
            ]
        }
    ]
}

Note

The Cloud Username and Network ID information will not be visible in the contact detail page. It may be visible in the list of messaging group contacts.

External Provisioning requirements¶

For multi tenant applications, the external provisioning endpoint is required to provide the Network ID for the user. In case a Network ID is not provided via external provisioning, the Network ID will be set to the Cloud ID of the application.

Note

Single-tenant applications don’t need to provide Network ID in the external provisioning response. In case the Network ID is not provided, the local user Network ID will be set to the Cloud ID of the application.

An example External Provisioning response including the Network ID of the user follows:

<account>
  <username>B63349F4EE</username>
  <password>45F4BF5F0E191F5DCC27</password>
  <networkId>myNetwork</networkId>
</account>

Please refer to External Provisioning for more information.

SMS Gateway Integration¶

For SMS gateway integration with providers such as Sinch or Bandwidth (optional), the external provisioning endpoint must return a list of SMS numbers in the provisioning response.

This is an example of what needs to be added under the <account> tag:

<account>
  <username>B63349F4EE</username>
  <password>45F4BF5F0E191F5DCC27</password>
  <networkId>myNetwork</networkId>
  <smsNumbers>
    <number>
      <carrier>sinch</carrier>
      <number>1234567890</number>
    </number>
    <number>
      <carrier>sinch</carrier>
      <number>1234567891</number>
    </number>
  </smsNumbers>
</account>

Note

The SMS numbers configuration is optional and only required if the customer wants to use SMS gateway integration.

iOS Notification Extension¶

CloudSoftphone whitelabel applications need to be configured to use notification extension. If your application is a Full-Service application, our support team will enable it for you.