Rate Checker¶

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 Global parameters and Account parameters 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 Account XML - see rateCheckMinNumberLength.

smartUri ¶

In case 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 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):
<genericRateCheckUrl>https://example.com/rate/?username=%account[username]%&amp;targetNumber=%targetNumber%</genericRateCheckUrl>
Example (without query-string):
<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):
username=%account[username]%&amp;targetNumber=%targetNumber%
Example ( for application/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:

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:

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:

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:

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