Click-2-call

From PokeTALK developers

Jump to: navigation, search

Contents

Description

The Click-2-Call API allows you to trigger calls from any application by sending a few POST parameters to http://www.poketalk.com/index.php/api/click2call


Getting started

- Make sure you have a positive balance in your PokeTALK account to be able to place calls.

- Register for an API-Key with PokeTALK. You will need to supply the IP address which call requests will be triggered from (for help with this email developers@poketalk.com)


Parameters

Required Name Type Description
required to string full e164 phone number in international format (i.e 1212xxxxxxx)
required from string full e164 phone number in international format (i.e 1212xxxxxxx)
required api_key string Your API-Key as supplied to you by PokeTALK
not required custom string Custom string which you can query to find this specific record. (max 255 chars)
not required eventurl string URL for sending events about changes of call status (max 255 chars), see EventURL section.

Response 

 
Parameter Type Description
00 int OK
10 int ERROR. Empty 'api_key' parameter.
20 int ERROR. Empty 'from' parameter.
30 int ERROR. Empty 'to' parameter.
40 int ERROR. Unknown API user.
50 int ERROR. Can`t get service provider.
60 int ERROR. 'from' or 'to' number in blacklist.
70 int ERROR. Can`t get gateway list.
90 int ERROR. Can`t calculate timeout.
100 int ERROR. Unknown API IP address.

Good Practice

- In many countries the leading zero needs to be removed from the number before adding the country prefix, for example, 972054xxxxxxx would be incorrect, whilst 97254xxxxxx would be correct

- For your security, it is good practice to send the call request using "from" or "to" numbers which are pre-stored in your database, and NOT via client-side forms which can be manipulated.


from users of your application it is important that requests sent to PokeTALK containing the "from"


EventURL

Using EventURL you may check status of the initiated call and terminate call, if cost was exceeded or for any other reason.

EventURL may contain following run-time variables in the query part of the URL, which will be replaced with current values:

$webcallid - unique id of the call, set in 'custom' parameter to identify specific call

$status - status of the call, may have one of the following values:

0 - unknown state (indicate some issue)

1 - CallA initiated

2 - CallA failed

3 - CallA answered

4 - CallA disconnected (before CallB was answered)

5 - CallB initiated

6 - CallB failed

7 - CallB answered

8 - CallAB disconnected (after CallB was answered)

$duration - duration of the call (sec)

$debit - current debit corresponding to duration


Server sends HTTP 'GET' request to specified URL each time when status is changing or every 60 sec after CallA was answered

Format of EventURL:

http://<host>[:<port>]/call_report.php?webcallid=$webcallid&status=$status&duration=$duration&debit=$debit

where <port> is optional, and any variable may be omitted


Example of HTTP request and positive response: 

GET /call_report.php?webcallid=web1323041193&status=1&duration=0&debit=0.000 HTTP/1.0
Host: my.host.com
User-Agent: ARS 0.1
Accept: */*


HTTP/1.1 200 OK
Date: Sun, 04 Dec 2011 23:26:33 GMT
Server: Apache/2.2.3 (CentOS)
X-Powered-By: PHP/5.1.6
Content-Length: 0
Connection: close
Content-Type: text/html; charset=UTF-8


If you want to terminate call, then HTML code '412 Precondition Failed' should be returned.

Example of HTTP request and negative response (terminate call): 

GET /call_report.php?webcallid=web1323041193&status=7&duration=300&debit=0.515 HTTP/1.0
Host: my.host.com
User-Agent: ARS 0.1
Accept: */*


HTTP/1.1 412 Precondition Failed
Date: Sun, 04 Dec 2011 23:31:33 GMT
Server: Apache/2.2.3 (CentOS)
X-Powered-By: PHP/5.1.6
Content-Length: 0
Connection: close
Content-Type: text/html; charset=UTF-8

NOTE: it may take few seconds until call will be really disconnected


Example PHP code, which terminate each call longer than 5 min: 

<?php
$status = $_REQUEST['status'];
$duration = $_REQUEST['duration'];
$max_duration = 300;
if ($status == '7' && $duration >= $max_duration)
{
       //disconnect any call longer than $max_duration sec
       header('HTTP/1.1 412 Precondition Failed');
}
else
{
       header('HTTP/1.1 200 OK');
}

?>
Retrieved from "http://developers.poketalk.com/index.php/Click-2-call"
Personal tools