.. _invitation_accept:

===================
Invitation Accepted
===================

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

Overview
--------

.. note::
    - INVITER - the person who has invited someone from his contacts
    - INVITEE - the person who has been invited

When "contact sync" and "smart contacts" features are enabled for Cloud Softphone apps, users can invite people from
their address books to join the same network.

Invitations are collected by Acrobits Contacts server, which also detects when an invited user joins the service. When
it happens, it can report this event via a web service described in this document.

This gives provider a chance to give some benefit to users who brought more people to use the service and notify them
via SMS, email or any other way about this fact. The web service is called from Contacts server and must be implemented
by provider.

Parameters
----------

The parameters for this web service are fixed: ``invitee``, ``invitor``, ``network_id``. No other parameter keywords are
recognized.

``invitee``
~~~~~~~~~~~
    The phone number of the invited user who just joined the service.

``invitor``
~~~~~~~~~~~
    SIP username of the user who invited `invitee`.

``network_id``
~~~~~~~~~~~~~~
    This will be typically Cloud ID of the Cloud Softphone application. In case provider sends `network_id` in the
    response of :ref:`ext_auth` web service, it will be used here as well.

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

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

``invitationAcceptedUrl``
~~~~~~~~~~~~~~~~~~~~~~~~~

    Contains the URL, including URL scheme, of the web service. If you wish to use GET method, specify the query string
    here as well.

    Example (with query-string):

    .. code-block:: none

        https://example.com/invitation/?invitee=%invitee%&invitor=%invitor%&net=%network_id%

``invitationAcceptedPostData``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    If filled in, Contacts server will use HTTP POST method to report the accepted invitation.

    Example (for application/json):

    ..code-block:: json

        { "invitee" : "%invitee%", "invitor" : "%invitor%", "network" : "%network_id%" }


``invitationAcceptedContentType``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Specifies the value of Content-Type header to be sent in the request. If not specified, the app will default
    to application/x-www-form-urlencoded. Supported content types are:

        - application/json
        - application/x-www-form-urlencoded
        - 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. Because both webservices have same format here
    is example of just second webservice.

Examples
--------

GET method
~~~~~~~~~~

request:

 .. code-block:: http

    GET /invitation_accept/?invitee=15551231234&invitor=johnsnow&network_id=mynetwork HTTP/1.1
    Host: example.com
    Connection: close
    Cache-Control: max-age=0
    User-Agent: Sync Server 1.0


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, XML
~~~~~~~~~~~~~~~~

request:

 .. code-block:: http

    POST /invitation_accept/ 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>
        <invitee>15551231234</invitee>
        <invitor>johnsnow</invitor>
        <network_id>mynetwork</network_id>
    </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 /invitation_accept/ 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

    {"invitee" : "15551231234", "invitor" : "johnsnow", "network_id" : "mynetwork"}

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