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

Response

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:

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:

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');
}

?>

    ptReport.create(from_date, to_date, callback);

    var result = ptReport.create(from_date, to_date);

 
    {"start_balance":float,
     "result":[
               {"date":date,
                "from":string,
                "to":string,
                "billsec":integer,
                "credit":float,
                "debit":float
                 },
            {...},
            {...},
            {...}
        ]
    }

var item;
var html   = "";
// Get billing records for January 2009
var report = ptReport.create("2008-12-31", "2009-02-01");
if(!report.result){
    html = 'No billing records for this period';
}else{
    // Get report length
    var len = report.result.length;
    // Create report HTML
    for(var i=0; i<len; i++){
        item = report.result[i];
        // Print calls records only
        if(item.debit != 0){
            html += item.date+" "+item.from+" "+item.to+" "item.billsec+" "+item.debit+"<br />";
        }
    }
}
// Print HTML
document.write(html);

ptReport.create("2008-12-31", "2009-02-01", function(report){
    if(!report.result){
        alert('No billing records for this period');
        return;
    }
    var item;
    var html = "";
    // get report length
    var len = report.result.length;
    // create contact list HTML
    for(var i=0; i<len; i++){
        item = report.result[i];
        // Print calls records only
        if(item.debit != 0){
            html += item.date+" "+item.from+" "+item.to+" "item.billsec+" "+item.debit+"<br />";
        }
    }
    // print HTML
    document.write(html);
});

    ptAddressbook.get_contacts(callback);

    var result = ptAddressbook.get_contacts();

 
    {"result":[
            {"id":integer,
             "contact_name":string,
             "company":string,
             "code":string,
             "value":string,
             "code_1":string,
             "value_1":string,
             "code_2":string,
             "value_2":string,
             "email":string },
            {...},
            {...},
            {...}
        ]
    }

function print_contacts(){
    var item;
    var html = "";
    // insert user contact list into data object
    var data = ptAddressbook.get_contacts();
    if(!data.result){
        alert('Your addressbook is empty');
        return;
    }
    // get contact list length
    var len = data.result.length;
    // create contact list HTML
    for(var i=0; i<len; i++){
        item = data.result[i];
        html += "Name: "+item.contact_name+" Phone:+"+item.code+"-"+item.value+"<br />";
    }
    // print HTML
    document.write(html);
}

/* insert user contact list into data object */
ptAddressbook.get_contacts(function(data){
    if(!data.result){
        alert('Your addressbook is empty');
        return;
    }
    var item;
    var html = "";
    // get contact list length
    var len = data.result.length;
    // create contact list HTML
    for(var i=0; i<len; i++){
        item = data.result[i];
        html += "Name: "+item.contact_name+" Phone:+"+item.code+"-"+item.value+"<br />";
    }
    // print HTML
    document.write(html);
});

    var is_mail = ptBase.is_email(address);

if(ptBase.is_email("lala@nana.com")){
    alert("Is valid address");
}else{
    alert("Not valid address");
}

    ptBase.login(email,password,remember_me,callback);

    var result = ptBase.check_login(email,password,remember_me);

 
   {"result":false,"code":1,"msg":"please enter a valid email address"}

 
   ptBase.login('example@poketalk.com','password', '1' , function(data){
       if (!data.result){
          alert (data.msg); //error
       } else {
          alert ('do something'); //user logged in successfully
       }
   });

    ptBase.logout();

    var result = ptBase.logout();

 
   {"result":boolean}

 
function logout(){
     ptBase.logout();
}

    ptBase.make_call(to_prefix,to_number,callback);

    var result = ptBase.make_call(to_prefix,to_number);

 
    [{"result":boolean,"code":intiger,"msg":string}]

ptBase.make_call('1','5551234567',function(data){
     if (!data.result) {
	 alert(data.msg);
     } else {
         alert("Now connecting");
     }
});

    ptAddressbook.remove_contact(id, callback);

    var result = ptAddressbook.remove_contact(id);

 
    {"result":boolean}

var data = ptAddressbook.remove_contact(id);
if(data.result){
    alert("Rmoved");
}else{
    alert("Can`t remove contact");
}

ptAddressbook.remove_contact(id, function(data){
    if(data.result){
        alert("Removed");
    }else{
        alert("Can`t remove contact");
    }
});

    ptBase.set_number(prefix,number,callback);

    var result = ptBase.set_number(prefix,number);

 
    {"result":boolean}

ptBase.set_number(prefix,phone,function(data){
     if (data.result==true) {
	alert ("New phone number set");
     } else {
        alert ("Oops, something went wrong");
     }
});

    var is_number = ptBase.test_number(phone_number);

if(ptBase.test_number("97231234567#321")){
    alert("Is number");
}else{
    alert("Not number");
}