Web Callback

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:

  1. user wants to call number 12345 via web callback. In account configuration, he set the callback number to 98765.

  2. app contacts web service and passes parameters targetNumber=12345, callbackNumber=98765. Other parameters may also be passed.

  3. web service returns success response. The app shows an info box with text “waiting for call”.

  4. 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 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 Global parameters and Account parameters 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 Account XML and referenced as %account[callbackNumber]%. The account node can be set either by 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 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:

<wcb_url>https://example.com/webcallback/?u=%account[username]%&amp;p=%account[password]%&amp;to=%targetNumber%&amp;callback=%account[callbackNumber]%</wcb_url>

wcb_postData

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

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

u=%account[username]%&amp;p=%account[password]%&amp;to=%targetNumber%&amp;callback=%account[callbackNumber]%

Example ( for application/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:

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:

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:

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:

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:

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."
}