API interface for free PBX and telephony

A few weeks ago, the Zadarma project published its own API. It allows you to integrate the basic functions of IP-telephony and free cloud PBX.
Everyone can create a free cloud PBX in few minutes and connect the API interface to it, and through it, integrate the PBX with their applications.
In the article we publish a list and description of methods, references to classes and examples that already exist (PHP classes are published). We are extremely interested in your feedback: for the further development of the API interface, integration with CRM and other systems.

The main functions available in the API:

• displaying and changing the settings of SIP accounts (including setting / changing number forwarding, the ability to bind to the SIM-card);
• balance display, selection of statistics with different details (both SIP and free PBX);
• making outgoing calls (CallBack function to external and internal numbers);
• sending SMS messages (outside the Russian Federation);
• notifying your server of each incoming call to the PBX, as well as the routing of these calls by your application.

Current functions will be enough for easy integration of CRM, call tracking and similar systems. We are open to suggestions for expanding the functionality of the API in future versions, for tighter integration with any services.
A full official description of all methods is available on the website .

Available examples and classes:

Today, the full PHP class is available for working with the API, you can download it on Github . There are examples of working with all its functions.
In addition to the official, there are alternative classes for working under PHP, and even for the Windows command line.
')

Authorization and getting started

To start working with the API, you must already have an account registered in the Zadarma system. If you need a free PBX / numbers / SIM-card , then they also better pre-enable.
Next you need to get the keys for authorization in your account .
Each request that needs authorization is accompanied by an additional header, of the form:
" Authorization: User Key: Signature"
The signature is made according to the following algorithm:

• The array of transmitted parameters (GET, POST, PUT, DELETE) is sorted by the name of the key alphabetically;
• a query string is formed from the resulting array (for example, the http_build_query function in PHP), an example is “from = DATEFROM & to = DATETO ...”;
• and further - connected by the formula:
• string = method_name + query_string + md5 (query_string),
• where “method_name” is a query string, starting from the domain (indicating the version of the API), before the beginning of the listing of parameters, for example - / v1 / sip / "
• The resulting string is cached using the sha1 algorithm with the user's private key:
• hash = hash (string, secret_key)
• and further the hash is encoded in base64
• signature = base64_encode (hash)

PHP example:

ksort($params); $paramsStr = http_build_query($params); $sign = base64_encode(hash_hmac('sha1', $method . $paramsStr . md5($paramsStr), $secret)); $header = 'Authorization: ' . $userKey . ':' . $sign; 

Format and limitations

Response formats: json (by default) and xml.
To get a response from the API in xml format, the parameter “format = xml” is added to the query string.
Each answer contains information about limits and the current request, for example:

 X-Zadarma-Method: /v1/ X-RateLimit-Reset: 1434371160 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99 

Where,

• X-Zadarma-Method - the current method being called;
• X-RateLimit-Remaining - the number of remaining requests, taking into account the limit on the method and per user;
• X-RateLimit-Limit - the total limit of hits per minute;
• X-RateLimit-Reset - time limit reset.

In the case of blocking, the method returns a response with the 429 header “You exceeded the rate limit”.
The answer consists of a mandatory key "status" (success or error). Further, depending on the method, they give their keys with the requested information.
In case of an error, an additional message key is given with a description of the error.

An example of an outgoing call through the API

Outgoing calls are made via CallBack (description of the Callback here ).
Scheme of work:

1. You receive an API request to the Zadarma server
2. You receive an incoming call and listen to the message “Wait for the call”
3. The server sends a second call to the phone of the subscriber you need.
4. When the subscriber answered the call, you can communicate.

Pay attention: both on the place of “your phone” and on the place of “the phone you are calling to” can be your SIP-login or internal PBX number. This allows you to make outgoing calls from office IP-phones / gateways / SIP programs as well as calls within the network.
Method name: / v1 / request / callback /
Options:

• from - your phone number or SIP, which is called callback;
• to - telephone or SIP phone number;
• sip (optional) - SIP-user number if he wants to use a specific CallerID assigned to this SIP-ohm;
• predicted (optional) - if this flag is specified, the request is predicative (the system initially calls the “to” number and only if it dials, connects to your SIP or telephone number);

Sample answer:
Json

 { "status":"success", "from": 442037691880, "to": 442037691881, "time": 1435573082 } 

XML

 <?xml version="1.0"?> <answer> <status>success</status> <from>442037691880</from> <to>442037691881</to> <time>1435573082</time> </answer> 

PHP example with Zadarma class:

 <?php include_once 'include.php'; $params = array( 'from' => '442037691880', 'to' => '442037691881', // 'sip' => 'YOURSIP' ); $zd = new \Zadarma_API\Client(KEY, SECRET); $answer = $zd->call('/v1/request/callback/', $params); $answerObject = json_decode($answer); if ($answerObject->status == 'success') { print_r($answerObject); } else { echo $answerObject->message; } 

Convenience for call centers

Especially for call centers there is the possibility of predicative dialing - the system initially calls the “to” number and only if it dials, connects to your SIP or telephone number.
For example: you have a large list of numbers where to call and several employees of a call center; with predictive dialing, you do not need employees to dial numbers one by one and wait for the result (losing working time).
For convenient call-up of numbers from the call center:

• pass the list of numbers through calls to the API callback function
• in the from parameter, specify the number of your free PBX, to which the call center employees are connected, also indicate the predicted flag
• is ready! The system will call your customers, and only if the customer picks up the phone and your employees receive an incoming call and the conversation begins. Considerable time savings for employees.

Note: The system will make such a call only if it has more than a quarter of valid numbers.

Incoming Call Notification

Zadarma system can send information about each incoming call to the virtual PBX and route the call to the desired extension number, depending on the answer. To do this, you need to create a public link that will receive POST requests with information from the Zadarma system.
In order for the system to accept the link, you must add a verification code at the beginning of the script.
PHP example:

 <?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?> 

Parameters that are sent to the callback link:

• caller_id - caller number;
• called_did - the number to which they called;
• callstart - the start time of the call

For each request, you can “on the fly” change the scenario for the current call by sending in response to the information:

 { "redirect": ID, "caller_name": NAME } 

Where,

• redirect — id of the redirect script or internal PBX number, or “blacklist” - in this case the call will be rejected with a busy signal;
• caller_name - you can give the name of the incoming number.

Sample PHP code:

 <?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); if ($_POST) { $callerId = $_POST['caller_id']; // number of calling party; $calledDid = $_POST['called_did']; // number of called party; $callstart = $_POST['callstart']; // start time of call /* // For each request you can easily change work scenario for current call by sending in response on information: echo json_encode(array( 'redirect' => 1, 'caller_name' => 'TestName' )); exit(); */ } 

Full list of API methods:

/ v1 / info / balance / - current user balance;
/ v1 / info / price / - the cost of the call, taking into account the current rate of the user;
/ v1 / request / callback / - callback request (described above);
/ v1 / sip / - list of user SIP-numbers;
/ v1 / sip / callerid / - change CallerID (from purchased or confirmed numbers);
/ v1 / sip / redirection / - display of current redirects on user SIP-numbers, redirection on / off, change of redirection parameters;
/ v1 / sms / send / - sending SMS;
/ v1 / statistics / - getting general statistics;
/ v1 / statistics / pbx / - statistics on free PBX.

In the future, an increase in the number of methods is planned. If you think that there are methods that need to be added to the API - write in the comments.