.. _notify_about_new_smartcontacts:

==============================
Notify About New Smartcontacts
==============================

.. contents::
    :local:
    :depth: 3

Overview
--------

When "contact sync" and "smart contacts" features are enabled for Cloud Softphone apps, you can set up webhook for notifying
about new smartcontacts.

This gives provider a change to notify other users that some of their friend from contact list become Smart. When
it happens, it can report this event via a web service described in this document.


Parameters
----------

The parameters for this web service are fixed: ``new_smart_number``, ``network_id``, ``new_smart_uri`` and ``interested_parties``. No other parameter keywords are recognized.

``new_smart_number``
~~~~~~~~~~~~~~~~~~~~
    The phone number of the new Smart user

``network_id``
~~~~~~~~~~~~~~
    The network of the new Smart user

``new_smart_uri``
~~~~~~~~~~~~~~~~~
    The sip uri of the new Smart user

``interested_parties``
~~~~~~~~~~~~~~~~~~~~~~
    List of users which have the new Smart user in their contact list. The structure of sending user is consisted of 2 properties - ``username`` and ``device``. For more information see example below.


Configuration
-------------

The web service is configured via Cloud Softphone web portal "Provisioning Options" (Step 2).


``smartContactNotificationUrl``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Contains the URL, including URL scheme, of the web service.

    Example:

    .. code-block:: none

        https://example.com/smartcontactnotification

``smartContactNotificationPostData``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Template for body. Because field interestedParties (interested_parties) is array it's not easy to write template for it.
    For simplification it will be replace always with same content depending on given content type. For more information see examples below.
    Please take also look that value of ``%interestedParties%`` is not wrapped in quotation marks in JSON template because it's expanded as
    an array in JSON.

    Example (for application/json):

    .. code-block:: json

        {
            "newSmartNumber" : "%new_smart_number%",
            "networkId" : "%network_id%",
            "newSmartUri" : "%new_smart_uri%",
            "interestedParties" : "%interestedParties%"
        }

    Example (for application/xml):

    .. code-block:: xml

        <root>
            <new_smart_number>%new_smart_number%</new_smart_number>
            <network_id>%network_id%</network_id>
            <new_smart_uri>%new_smart_uri%</new_smart_uri>
            <interested_parties>%interestedParties%</interested_parties>
        </root>


``smartContactNotificationContentType``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Specifies the value of Content-Type header to be sent in the request. Supported content types are:

        - application/json
        - application/xml

Response
--------

    The response will be considered successful if the HTTP response code is 204. Any responses which have other
    response code are silently ignored.

    See the examples below for the recognized formats of the responses.

Examples
--------


POST method, XML
~~~~~~~~~~~~~~~~

request:

 .. code-block:: http

    POST /smartcontactnotification/ HTTP/1.1
    Host: example.com
    Connection: close
    Cache-Control: max-age=0
    User-Agent: Sync Server 1.1
    Content-Type: application/xml
    Content-Length: 66

    <root>
        <new_smart_number>+420111222333</new_smart_number>
        <network_id>network_1</network_id>
        <new_smart_uri>sip_uri_1</new_smart_uri>
        <interested_parties>
            <list>
                <party>
                    <username>eric</username>
                    <device>erics_iphone</device>
                </party>
                <party>
                    <username>madelaine</username>
                    <device>madelaines_android</device>
                </party>
            </list>
        </interested_parties>
    </root>

response:

 .. code-block:: http

    HTTP/1.1 204 No Content
    Date: Sun, 15 Mar 2015 00:46:17 GMT
    Server: Apache/2.4.7 (Ubuntu)
    Vary: Accept-Encoding
    Content-Length: 123
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive

POST method, JSON
~~~~~~~~~~~~~~~~~

request:

 .. code-block:: http

    POST /smartcontactnotification/ HTTP/1.1
    Host: example.com
    Connection: close
    Cache-Control: max-age=0
    User-Agent: CloudSoftphone/1.5.6
    Content-Type: application/json
    Content-Length: 66

    {
        "newSmartNumber" : "15551231234",
        "networkId" : "mynetwork",
        "newSmartUri" : "johnsnow@pbx.acrobits.net",
        "interestedParties" : [
            {
                "username": "eric",
                "device": "erics_iphone"
            },
            {
                "username": "madelaine",
                "device": "madelaines_android"
            }
        ]
    }

response:

 .. code-block:: http

    HTTP/1.1 204 No Content
    Date: Sun, 15 Mar 2015 00:46:17 GMT
    Server: Apache/2.4.7 (Ubuntu)
    Vary: Accept-Encoding
    Content-Length: 123
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive