.. _turnkey_messaging_requirements:


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 :ref:`allowlist`.
    #.  **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 :ref:`ext_auth` 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 :ref:`external-provisioning-requirements`.

The messaging contact list can be currently provided as a :ref:`web_contacts` source or a CardDAV contact source.

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

 .. code-block:: json

    {
        "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:

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 :ref:`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 :ref:`cloud-id` of the application.

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

 .. code-block:: xml

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

Please refer to :ref:`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:

 .. code-block:: xml

    <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.