Balance Checker

Overview

This web service allows the app to check account credit balance and display it to the user. Balance is shown on the keypad screen.

Parameters

Parameter templates for Balance Checker can use any variables from Global parameters and Account parameters scopes. There are no service-specific parameters defined for balance checker.

Configuration

The following Account XML keys are relevant for balance checker configuration:

genericBalanceCheckUrl

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

Example (with query-string):

<genericBalanceCheckUrl>https://example.com/balance/?username=%account[username]%</genericBalanceCheckUrl>

Example (without query-string):

<genericBalanceCheckUrl>https://example.com/balance/%account[username]%</genericBalanceCheckUrl>

genericBalanceCheckPostData

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

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

username=%account[username]%

Example ( for application/json ):

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

genericBalanceCheckContentType

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

balanceCheckIntervalInSeconds

Specifies how often will the app check for balance updates. The default value is 300 (every 5 minutes).

Example:

<balanceCheckIntervalInSeconds>180</balanceCheckIntervalInSeconds>

balanceCheckDelayInSeconds

The app also checks for new balance when the call ends, because it’s expected that the balance changes at that time and it’s desired to refresh it asap.

Some providers may need to delay this check, because the new balance needs some time to propagate through their backend. The default is 5 seconds.

Example:

<balanceCheckDelayInSeconds>0</balanceCheckDelayInSeconds>

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.

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:

balanceString

This is the string which will be displayed as-is as a balance. The server needs to format this string to make it look pretty and follow the conventions for the given country and currency. It’s recommended to keep the balance string short (under 10 characters)

This field is mandatory.

balance

Numerical representation of the balance. Parsed as a floating-point number.

Optional and currently not used in the app

currency

Code of the currency in which the balance is expressed.

Optional and currently not used in the app

Examples

GET method, XML

request:

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

<response>
    <balanceString>CHF 13.44</balanceString>
    <balance>13.44</balance>
    <currency>CHF</currency>
</response>

GET method, JSON

request:

GET /balance/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 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

{
    "balanceString" : "CHF 13.44",
    "balance" : 13.44,
    "currency" : "CHF"
}