.. _rate_checker:

============
Rate Checker
============

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

Overview
--------

This web service allows the app to check rate for call and/or message for a given phone number. The web service is called
when user is typing digits in keypad screen, whenever the typing stops for cca 1 second. This means that the web service
may actually be called several times for different prefixes of the number.

The responses are cached; the app should not generate a second request for the same number within 2 hours.

The call rate is shown on keypad screen and in-call screen when available.

Parameters
----------

Parameter templates for Rate Checker can use any variables from :ref:`global-params` and :ref:`account-params`
scopes. There is also one specific parameter for rate checker.


targetNumber
~~~~~~~~~~~~
    This parameter is replaced by the destination number the user wants to call or send message to. For example, if
    user enters "+1 (555) 123-1234" on the keypad, the parameter will have value "+15551231234".

    The app tries to obtain the rate as fast as possible, knowing that the rate will most likely depend only on the
    first few digits. It may request rate for different prefixes of this number. The minimum length to ask for can be
    specified in :ref:`account-xml` - see `rateCheckMinNumberLength`.

smartUri
~~~~~~~~
    In case :ref:`smart_contacts` functionality is enabled in the app, the targetNumber may have been recognized as
    "smart" number. In this case, the app will know a SIP URI to make on-net call to this user and will pass this as
    ``smartUri`` parameter to rate checker. If targetNumber is not "smart", this parameter will be empty.

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

The following :ref:`account-xml` keys are relevant for rate checker configuration:

``genericRateCheckUrl``
~~~~~~~~~~~~~~~~~~~~~~~

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

    Example (with query-string):

    .. code-block:: xml

        <genericRateCheckUrl>https://example.com/rate/?username=%account[username]%&amp;targetNumber=%targetNumber%</genericRateCheckUrl>

    Example (without query-string):

    .. code-block:: xml

        <genericRateCheckUrl>https://example.com/rate/%account[username]%/%targetNumber%</genericRateCheckUrl>

``genericRateCheckPostData``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    If filled in, the app will use POST request to check the rate.

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

    .. code-block:: xml

        username=%account[username]%&amp;targetNumber=%targetNumber%

    Example ( for  application/json ):

    .. code-block:: json

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

``genericRateCheckContentType``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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


``rateCheckMinNumberLength``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    The web service will only be called for numbers whose length is greater than the number specified here. The default
    setting is 2.


Response
--------

    The response will be considered successful if the HTTP response code is 2xx. Any responses which have other
    response code, or whose body can't be parsed, are silently ignored. If you can't figure out the rate for some
    reason (like when the prefix is not long enough yet), you may either respond with some non-2xx code, or send a
    correct response with some generic text instead of rate, like "?" or an empty string.

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

``callRateString``
~~~~~~~~~~~~~~~~~~
    This is the string which will be displayed as the rate for making a call to the given number. The string may return
    price with currency and also some timing specification, like "/min" or "per minute". The string is displayed as-is.
    Note that there is limited space and strings which are too long may be cropped.

``messageRateString``
~~~~~~~~~~~~~~~~~~~~~
    The rate for sending a text message to the given number.

``smartCallRateString``
~~~~~~~~~~~~~~~~~~~~~~~
    The rate to show in case the user makes on-net call to the given ``smartUri``. The app will prefer to make on-net
    calls by default.

``smartMessageRateString``
~~~~~~~~~~~~~~~~~~~~~~~~~~
    The rate for sending an on-net text message to the given ``smartUri``.

Examples
--------

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

request:

 .. code-block:: http

    GET /rate/?username=johndow&password=12345678&targetNumber=%2B1800 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)
    Vary: Accept-Encoding
    Content-Encoding: gzip
    Content-Length: 183
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive
    Content-Type: text/xml

    <response>
        <callRateString>2¢ / min</callRateString>
        <messageRateString/>
    </response>


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

request:

 .. code-block:: http

    GET /rate/johndow/12345678/%2B420 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)
    Vary: Accept-Encoding
    Content-Encoding: gzip
    Content-Length: 183
    Keep-Alive: timeout=5, max=100
    Connection: Keep-Alive
    Content-Type: application/json

    {
        "callRateString" : "1¢ / min",
        "messageRateString" : "5¢"
    }