Web Call-Through¶

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 Global parameters and Account parameters scopes.

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.

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 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):
<cth_ws_url>https://example.com/callthrough/?u=%account[username]%&amp;to=%targetNumber%</cth_ws_url>
Example (without query-string):
<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):
username=%account[username]%&to=%targetNumber%
Example ( for application/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 Global parameters and Account parameters are available.

Examples ¶

GET method, XML ¶

request:

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:

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:

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

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