.. _web_callthrough:

================
Web Call-Through
================

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

Overview
--------

In call-through, the long-distance calls are realized by calling a local access number and using DTMF tones to enter
the destination number to call to, along with optional PIN codes for authentication etc.

While call-through feature can work without a web service, adding a web service adds additional flexibility, at the cost
of requiring internet access.

The call flow for web-callback is as follows:

 #) user decides to call number 12345 via call-through
 #) app contacts web service and passes the number 12345 as a parameter
 #) web service decides how the number should be dialed and sends back full dial string
 #) app dials the returned dial string

.. note::

  In step 2, the app can pass various arguments to the web service, including the username / password of the user. The
  server can also find the location of the user by checking the IP address the request came from and using GeoIP
  database to find the location.

  In case the server knows mapping between the username and user's phone number, it can also return the dial string with
  just the access number and remember a rule: *if there is an incoming call to access number A from number X within the
  next minute, it is user Y who wants to call to number 12345*. This completely eliminates the need of DTMF signalling.

Parameters
----------

Parameter templates for Web Call-Through can use any variables from :ref:`global-params` and :ref:`account-params`
scopes.

.. warning::
  Password can only be sent via  web service which uses HTTPS url scheme. See **nonce** and **sha1** in
  :ref:`template-functions` for details on how to send a salted SHA-1 hash of password instead.

There is also one additional, service-specific parameter:

targetNumber
~~~~~~~~~~~~
    This is a parameter specific to Web Call-Through web service and is replaced by the destination number the user
    wants to call. For example, if the user enters "+1 (555) 123-1234" on the keypad and initiates the call-through dial
    action, the parameter will have value "+15551231234".

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

The following :ref:`account-xml` keys are relevant for callthrough web service configuration:

``cth_ws_url``
~~~~~~~~~~~~~~

    Contains the URL, including URL scheme, of the web service, possibly also with query string.

    Example (with query-string):

    .. code-block:: xml

        <cth_ws_url>https://example.com/callthrough/?u=%account[username]%&amp;to=%targetNumber%</cth_ws_url>

    Example (without query-string):

    .. code-block:: xml

        <cth_ws_url>https://example.com/callthrough/%account[username]%/%targetNumber%</cth_ws_url>

``cth_ws_postData``
~~~~~~~~~~~~~~~~~~~

    If filled in, the app will use POST request to call the web service.

    Example ( for  application/x-www-form-urlencoded):

    .. code-block:: none

        username=%account[username]%&to=%targetNumber%

    Example ( for  application/json ):

    .. code-block:: json

        { "username" : "%account[username]%", "to" : "%targetNumber%" }

``cth_ws_contentType``
~~~~~~~~~~~~~~~~~~~~~~

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

Response
--------

    The response will be considered successful if the HTTP response code is 2xx. Any responses which return other
    response code, an error message is shown to the user. The text of the message is taken from `message`_ parameter
    of the response. If the parameter is empty or not present at all, the response is silently ignored.

    ``Content-type`` header of the response specifies the format of the body. The following Content-Types are supported:

        - application/xml  (**default**)
        - application/json
        - application/x-www-form-urlencoded

    The following fields in the response are recognized:

``message``
~~~~~~~~~~~
    This parameter should be included in case the web service returns non-2xx response code. The contents of this
    parameter will be shown to the user

``dialString``
~~~~~~~~~~~~~~
    In case of 2xx response code, this will be the string to dial. This string will be passed to the native dialer to
    call the number via the cellular service.

.. note::

    This dial string MAY also contain parameter placeholders same as the query string. Both :ref:`global-params`
    and :ref:`account-params` are available.

Examples
--------

GET method, XML
~~~~~~~~~~~~~~~

request:

 .. code-block:: http

    GET /callthrough/?username=johndow&targetNumber=12345678 HTTP/1.1
    Host: example.com
    Connection: close
    Cache-Control: max-age=0
    User-Agent: CloudSoftphone/1.5.6


response:

 .. code-block:: http

    HTTP/1.1 200 OK
    Date: Sun, 15 Mar 2015 00:46:17 GMT
    Server: Apache/2.4.7 (Ubuntu)
    Content-Length: 183
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive
    Content-Type: text/xml

    <response>
        <dialString>+15551231234,,%account[x-cth-pin]%#12345678#</dialString>
    </response>

The account parameter ``x-cth-pin`` can be present in account XML as a result of external provisioning, or via custom
account forms. If this parameter contains 1234, the final dial string will be ``+15551231234,,1234#12345678#``

GET method, JSON
~~~~~~~~~~~~~~~~

request:

 .. code-block:: http

    GET /callthrough/johndow/12345678 HTTP/1.1
    Host: example.com
    Connection: close
    Cache-Control: max-age=0
    User-Agent: CloudSoftphone/1.5.6


response:

 .. code-block:: http

    HTTP/1.1 403 Forbidden
    Date: Sun, 15 Mar 2015 00:46:17 GMT
    Server: Apache/2.4.7 (Ubuntu)
    Content-Length: 183
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive
    Content-Type: application/json

    {
        "message" : "Not enough credit for call-through."
    }