.. _web_callback: Web Callback ============ .. contents:: :local: :depth: 3 Overview -------- In web callback, the long-distance calls are realized by doing web service request and passing destination number and callback number as parameters. The callback number is typically phone number of the mobile device, but it can be any phone number which can receive incoming calls. The server should call the destination number, then the callback number and connect these two calls together. The call flow for web callback is as follows: #) user wants to call number 12345 via web callback. In account configuration, he set the callback number to 98765. #) app contacts web service and passes parameters targetNumber=12345, callbackNumber=98765. Other parameters may also be passed. #) web service returns success response. The app shows an info box with text "waiting for call". #) web service calls number 12345 and 98765. When these calls are answered, it connects them together. .. 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. .. 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. Parameters ---------- Parameter templates for Web Callback can use any variables from :ref:`global-params` and :ref:`account-params` scopes. targetNumber ~~~~~~~~~~~~ This is a parameter specific to Web Callback 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 web callback dial action, the parameter will have value "+15551231234". .. note:: The other required parameter - callback number - is typically taken from :ref:`account-xml` and referenced as %account[callbackNumber]%. The account node can be set either by :ref:`external-provisioning` or by adding a field into "edit account" form, where user can fill this number manually. Ask Acrobits representative for more details about how to customize the account forms for Cloud Softphone. Configuration ------------- The following :ref:`account-xml` keys are relevant for balance checker configuration: ``wcb_url`` ~~~~~~~~~~~ Contains the URL, including URL scheme, of the web service, possibly also with query string. Example: .. code-block:: xml https://example.com/webcallback/?u=%account[username]%&p=%account[password]%&to=%targetNumber%&callback=%account[callbackNumber]% ``wcb_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 u=%account[username]%&p=%account[password]%&to=%targetNumber%&callback=%account[callbackNumber]% Example ( for application/json ): .. code-block:: json { "username" : "%account[username]%", "password" : "%account[password]%", "to" : "%targetNumber%", "callback" : "%account[callbackNumber]%" } ``wcb_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 app will show a message box with first 100 characters of response body. In case of successful response, the app shows an info box with text "waiting for call". This box is dismissed automatically when incoming call arrives to the app, or it can be dismissed manually by user. ``Content-type`` header of the response specifies the format of the body. The following Content-Types are supported: - application/xml - application/json - application/x-www-form-urlencoded The following fields in the response are recognized: .. _callback-message: ``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. Examples -------- GET method, XML ~~~~~~~~~~~~~~~ request: .. code-block:: http GET /webcallback/?username=johndow&password=123456&callbackNumber=98765&targetNumber=12345 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: 0 Keep-Alive: timeout=5, max=100 Connection: Keep-Alive POST method, JSON ~~~~~~~~~~~~~~~~~ request: .. code-block:: http POST /webcallback/ HTTP/1.1 Host: example.com Connection: close Cache-Control: max-age=0 Content-Length: 183 Content-Type: application/json User-Agent: CloudSoftphone/1.5.6 { "username" : "johndow", "password" : "secretW0rd", "to" : "+15551231234", "callback" : "+15559879876" } 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 this call." }