fb
  • Services
  • Pricing
  • Solutions
  • Support

API

The Zadarma API interface allows clients to use our service for their personal applications, and to integrate it with any CRM system as well as softphones for call centers. It is quite easy for a client to set up a cloud PBX and connect it with the API interface in order to integrate Zadarma’s business phone system with their own applications.

Main functions available in the API:

  • SIP account and PBX settings display and changing;
  • Statistics and balance display;
  • Calls and SMS (CallBack to internal and external numbers);
  • External server notifications for incoming calls and call routing.

API link: https://api.zadarma.com

API version: v1

Final link on method: https://api.zadarma.com/v1/METHOD/

PHP and Python classes are available for download on GitHub.

Integration manual for your own CRM and Zadarma telephony

Authorization

Each authorization request should be sent with an additional header:
"Authorization: user_key: signature"

Authorization keys must be generated in your personal account.

The signature is made according to the following algorithm:

  • The array of transmitted data (GET, POST, PUT, DELETE) is sorted by the key name in alphabetical order;
  • The received array forms the query strip (for example, http_build_query function in PHP), example "from=DATEFROM&to=DATETO…";
  • It is then concatenated as follows: line = method_name request_line md5(request_line), where “method_name” is the request line after the domain (with indication of API version) till the beginning of the parameters list, for example - '/v1/sip'
  • The resulting string is hashed by the algorithm sha1 with the secret user key: hash = hash( string, secret_key )
  • And then the hash is encrypted in base64 signature = base64_encode( hash )

PHP Example:

ksort($params);

$paramsStr = http_build_query($params, null, '&', PHP_QUERY_RFC1738);

$sign = base64_encode(hash_hmac('sha1', $method . $paramsStr . md5($paramsStr), $secret));

$header = 'Authorization: ' . $userKey . ':' . $sign;

You can download the complete PHP class for Zadarma API on GitHub.

The response formats: json (default) and xml.

To get the response from the API in xml format, the “format=xml” parameter must be added to the request line.

Restrictions

Each response contains information about the 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 - current requested method;
  • X-RateLimit-Remaining - the amount of requests remaining after taking into account the method and user limits;
  • X-RateLimit-Limit - the total number of request limits per minute;
  • X-RateLimit-Reset - limit reset time.

Total limits - 100 requests per minute, for statistics methods - 10 requests per minute.

In case of blocking, the method returns the response with 429 header "You exceeded the rate limit".

The response contains a mandatory "status" key (success or error). Afterwards, depending on the method, corresponding keys are provided with the requested information.

In case of an error, additional "message" key is provided with an error description.

Also all responses are provided with corresponding HTTP-headers.

Example of an error response:

JSON:

	{
		"status":"error",
		"message":"Check phone's number"
	}

XML:

	<?xml version="1.0"?>
	<answer>
		<status>error</status>
		<message>Check phone's number</message>
	</answer>

Available methods:

  • /v1/info/balance/
    user balance.
  • /v1/info/price/
    call rate in the user's current price plan.
  • /v1/info/timezone/
    user's timezone.
  • /v1/tariff/
    information about the user's current price plan.
  • /v1/request/callback/
    callback.
  • /v1/sip/
    the list of user's SIP-numbers.
  • /v1/sip/<SIP>/status/
    The user's SIP number online status.
  • /v1/sip/callerid/
    changing of the CallerID.
  • /v1/sip/redirection/
    Display of the current call forwarding based on the user's SIP numbers.
  • /v1/direct_numbers/
    information about the user's phone numbers.
  • /v1/sip/redirection/
    call forwarding switch on/off based on the SIP number.
  • /v1/sip/redirection/
    changing of the call forwarding parameters.
  • /v1/pbx/internal/
    the PBX extension numbers display.
  • /v1/pbx/internal/<PBXSIP>/status/
    online status of the PBX extension number.
  • /v1/pbx/internal/recording/
    enabling of the call recording on the PBX extension number.
  • /v1/pbx/record/request/
    call recording file request.
  • /v1/pbx/redirection/
    changing of the call forwarding parameters on the PBX extension number.
  • /v1/pbx/redirection/
    receiving call forwarding parameters on the PBX extension number.
  • /v1/sms/send/
    sending the SMS messages.
  • /v1/statistics/
    receive overall statistics.
  • /v1/statistics/pbx/
    PBX statistics.
  • /v1/statistics/callback_widget/
    CallBack widget statistics
  • /v1/info/number_lookup/
    user database check.
  • JSON
  • XML
{
    "status":"success",
    "balance":10.34,
    "currency":"USD"
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <balance>10.34</balance>
    <currency>USD</currency>
</answer>

Parameters:

  • number – phone number
  • caller_id (optional) – CallerID, which is used to make the call.

  • JSON
  • XML
{
    "status":"success",
    "info":{
        "prefix":"4420",
        "description":"United Kingdom, London",
        "price":"0.009",
        "currency":"USD",
    }
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <prefix>4420</prefix>
        <description>United Kingdom, London</description>
        <price>0.009</price>
        <currency>USD</currency>
    </info>
</answer>
  • JSON
  • XML
{
    "status":"success",
    "unixtime":1483228800,
    "datetime":"2017-01-01 00:00:00",
    "timezone":"UTC+0"
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <unixtime>1483228800</unixtime>
    <datetime>2017-01-01 00:00:00</datetime>
    <timezone>UTC+0</timezone>
</answer>
  • JSON
  • XML
{
    "status":"success",
    "info": {
        "tariff_id":5,
        "tariff_name":"Standart, special",
        "is_active":false,
        "cost":0,
        "currency":USD,
        "used_seconds":1643,
        "used_seconds_mobile":34,
        "used_seconds_fix":726,
        "tariff_id_for_next_period":5,
        "tariff_for_next_period":Standart, special
    }
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <tariff_id>5</tariff_id>
        <tariff_name>Standart, special</tariff_name>
        <is_active>false</is_active>
        <cost>0</cost>
        <currency>USD</currency>
        <used_seconds>1643</used_seconds>
        <used_seconds_mobile>726</used_seconds_mobile>
        <used_seconds_fix>726</used_seconds_fix>
        <tariff_id_for_next_period>5</tariff_id_for_next_period>
        <tariff_for_next_period>Standart, special</tariff_for_next_period>
    </info>
</answer>

where

  • tariff_id– user's current price plan ID;
  • tariff_name – the name of the user's current price plan;
  • is_active – the current price plan is active or inactive;
  • cost – the cost of the price plan;
  • currency – the price plan currency;
  • used_seconds – the amount of price plan seconds used;
  • used_seconds_mobile – the amount of price plan seconds used on calls to mobiles;
  • used_seconds_fix – the amount of price plan seconds used on calls to landlines;
  • tariff_id_for_next_period – the user's price plan ID for the next time period;
  • tariff_for_next_period – the name of the user's price plan for the next time period.

Parameters:

  • from – your phone/SIP number, the PBX extension number or the PBX scenario, to which the CallBack is made;
  • to – the phone or SIP number that is being called;
  • sip (optional) – SIP user's number or the PBX extension number (for example: 100), which is used to make the call. The CallerID of this number will be used; this SIP/PBX extension number will be displayed in the statistics; call recording and prefix dialling will be used if enabled for this number;

  • predicted (optional) – if this flag is specified the request is predicted (the system calls the “to” number, and only connects it to your SIP, or your phone number, if the call is successful.);
  • JSON
  • XML
{
    "status":"success",
    "from": 442037691880,
    "to": 442037691881,
    "time": 1435573082
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <from>442037691880</from>
    <to>442037691881</to>
    <time>1435573082</time>
</answer>
  • JSON
  • XML
{
    "status":"success",
    "sips":[
        {
            "id":"00001",
            "display_name":"SIP 1",
            "lines":3
        },
        {
            "id":"00002",
            "display_name":"SIP 2",
            "lines":3
        }
    ],
    "left":3
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sips>
        <value>
            <id>00001</id>
            <display_name>SIP 1</display_name>
            <lines>3</lines>
        </value>
        <value>
            <id>00002</id>
            <display_name>SIP 2</display_name>
            <lines>3</lines>
        </value>
    </sips>
    <left>1</left>
</answer>

where

  • id– SIP ID;
  • display_name – displayed name;
  • lines – the number of lines;
  • left – the number of remaining SIPs, which can be created (depends on the user's balance and the total number of SIPs already created).
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "is_online":"false"
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <is_online>false</is_online>
</answer>

Parameters:

  • id – the SIP ID, which needs the CallerID to be changed;
  • number – the new (changed) phone number, in international format (from the list of confirmed or purchased phone numbers.
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "new_caller_id":"442037691880"
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <new_caller_id>442037691880</new_caller_id>
</answer>

Parameters:

  • id – (optional) selection of the specific SIP ID.
  • JSON
  • XML
{
    "status":"success",
    "info": [
        {
        "sip_id":"00001",
        "status":"on",
        "condition":"always",
        "destination":"phone",
        "destination_value":"442037691880",
        },
    ...
    ]
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <value>
            <sip_id>00001</sip_id>
            <status>on</status>
            <condition>always</condition>
            <destination>phone</destination>
            <destination_value>442037691880</destination_value>
        </value>
    ...
    </info>
</answer>

where

  • sip_id – the user's SIP ID;
  • status – current status: on or off;
  • condition – call forwarding conditions: always – always (default), unavailable – when the call is unanswered or if there is no SIP connection;
  • destination – where the call is forwarded to: phone – to the phone number, pbx – to the PBX;
  • destination_value – the number for the call forwarding: phone number or the PBX ID.
  • JSON
  • XML
{
    "status":"success",
    "info": [
        {
            "number":"442037691880",
            "status":"on",
            "country":"Great Britain",
            "description":"London",
            "number_name":null,
            "sip":00001,
            "sip_name":null,
            "start_date":"2015-01-01 18:14:44",
            "stop_date":"2016-02-11 18:14:40",
            "monthly_fee":2,
            "currency":USD,
            "channels":2,
            "autorenew":"true",
            "is_on_test":"false",
            "type":"common"
        },
    ...
    ]
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <value>
            <number>442037691880</number>
            <status>on</status>
            <country>Великобритания</country>
            <description>Лондон</description>
            <number_name>null</number_name>
            <sip>00001</sip>
            <sip_name>Example</sip_name>
            <start_date>2015-01-01 18:14:44</start_date>
            <stop_date>2016-02-11 18:14:40</stop_date>
            <monthly_fee>2</monthly_fee>
            <currency>USD</currency>
            <channels>2</channels>
            <autorenew>true</autorenew>
            <is_on_test>false</is_on_test>
            <type>common</type>
        </value>
    ...
    </info>
</answer>

The fields can vary depending on the number type! The fields descriptions:

  • number – the user's purchased virtual phone number;
  • status – the phone number status;
  • country – country (for common and revenue);
  • description – description: city or type (for common and revenue);
  • number_name – the virtual phone number "name" (set by the user);
  • sip – the SIP connected to the phone number;
  • sip_name – the "name" of the SIP connected to the phone number;
  • start_date – the date of purchase;
  • stop_date – the end date of the user's payment period;
  • monthly_fee – the phone number cost (for common);
  • currency – the currency of the phone number cost (for common);
  • channels – the number of lines on the phone number (for common);
  • minutes – the total duration of incoming calls for the current month (for revenue);
  • autorenew – the automatic phone number extension is enabled or disabled (for common, revenue, rufree);
  • is_on_test – the phone number is being tested or not;
  • type – phone number type: common (virtual number), inum (free international number), rufree (free Moscow number), revenue (free Moscow 495 number)

Parameters:

  • id – SIP ID;
  • status – the call forwarding status on the selected SIP number.
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "current_status":"on"
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <current_status>on</current_status>
</answer>

Parameters:

  • id – SIP ID;
  • type – call forwarding type: phone – to the phone;
  • number – phone number.
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "destination":"442037691880"
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <destination>442037691880</destination>
</answer>
  • JSON
  • XML
{
    "status":"success",
    "pbx_id":1234,
    "numbers": [
        100,
        101,
        ...
    ]
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <pbx_id>1234</pbx_id>
    <numbers>
        <value>100</value>
        <value>101</value>
        ...
    </numbers>
</answer>

where

  • pbx_id – the user's PBX ID;
  • numbers – the list of extension numbers.
  • JSON
  • XML
{
    "status":"success",
    "pbx_id":1234,
    "number":100,
    "is_online":"false"
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <pbx_id>1234</pbx_id>
    <number>100</number>
    <is_online>false</is_online>
</answer>

where

  • pbx_id – PBX ID;
  • number – PBX extension number;
  • is_online – online-status (true|false).

Parameters:

  • id – PBX extension number;
  • status – status: "on" - switch on, "off" - switch off, "on_email" - enable the option to send the recordings to the email address only, "off_email" - disable the option to send the recordings to the email address only, "on_store" - enable the option to save the recordings to the cloud, "off_store" - disable the option to save the recordings to the cloud;
  • email – (optional) change the email address, where the call recordings will be sent. You can specify up to 3 email addresses, separated by comma.
  • JSON
  • XML
{
    "status":"success",
    "internal_number":100,
    "recording":"on",
    "email":"test@test.com"
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <internal_number>100</internal_number>
    <recording>on</recording>
    <email>on</email>
</answer>

Parameters:

  • call_id – unique call ID, it is specified in the name of the file with the call recording (unique for every recording);
  • pbx_call_id – permanent ID of the external call to the PBX (does not alter with the scenario changes, voice menu, etc., it is displayed in the statistics and notifications);
  • lifetime – (optional) the link's lifetime in seconds (minimum - 180, maximum - 5184000, default - 1800).

Note: It is enough to specify one of the two identification parameters (pbx_call_id or call_id), if pbx_call_id is specified, several links might be returned.

  • JSON
  • XML

Response example when only call_id is specified, only one link will be returned:

{
    "status":"success",
    "link": "https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
    "lifetime_till": "2016-01-01 23:56:22"
}

Response example when only pbx_call_id is specified, several links might be returned:

{
    "status":"success",
    "links":[
        "https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
        "https://api.zadarma.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3"
    ],
    "lifetime_till": "2016-01-01 23:56:22"
}

Response example when only call_id is specified, only one link will be returned:

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <link>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3</link>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
</answer>

Response example when only call_id is specified, several links might be returned:

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <links>
        <value>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3</value>
        <value>https://api.zadarma.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3</value>
    </links>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
</answer>

Parameters:

  • link – the link to the file with the conversation;
  • lifetime_till – until what time will the link work.

Parameters:

To switch on and set up the call forwarding:

  • pbx_number – PBX extension number in full, for example 1234-100;
  • status – on;
  • type – call forwarding type: voicemail or phone type;
  • destination – phone number or email address, depending on the previous parameter;
  • condition – call forwarding condition, possible values: always or noanswer;
  • set_caller_id – setting up your CallerID during the call forwarding, possible values: on, off. Specified only when type = phone;
  • voicemail_greeting – notifications about call forwarding, possible values: no, standart, own. Specified only when type = voicemail;
  • greeting_file – file with notification in mp3 format or wav below 5 MB. Specified only when type = voicemail and voicemail_greeting = own;

To switch on the call forwarding:

  • pbx_number – PBX extension number in full, for example 1234-100;
  • status – off;
  • JSON
  • XML
{
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
    }


<?xml version="1.0"?>
    <answer>
    <status>success</status>
    <current_status>on</current_status>
    <pbx_id>1234</pbx_id>
    <pbx_name>100</pbx_name>
    <type>phone</type>
    <destination>79123456789</destination>
    <condition>noanswer</condition>
    </answer>

Parameters:

  • pbx_number – PBX extension number in full, for example 1234-100;
  • JSON
{
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
    }

Parameters:

  • number – phone number, where to send the SMS message (several numbers can be specified, separated by comma);
  • message – message (standard text limit applies; the text will be separated into several SMS messages, if the limit is exceeded);
  • caller_id – (optional) phone number, from which the SMS messages is sent (can be sent only from list of user's confirmed phone numbers).
Please note: sending SMS messages is only available outside the Russian Federation
  • JSON
  • XML
{
    "status":"success",
    "messages":1,
    "cost":0.24,
    "currency":"USD"
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <value>
        <messages>1</messages>
        <cost>0.24</cost>
        <currency>1</currency>
    </value>
</answer>

Parameters:

  • start - the start date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • end - the end date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • sip (optional) - filter based on a specific SIP number;
  • cost_only (optional) - display only the amount of funds spent during a specific period;
  • type (optional - only for the overall statistics) - request type: overall (is not specified in the request), toll and ru495. (for the toll free numbers statistics and free 495 phone numbers).
  • skip (optional - not taken into account when the parameter is cost_only) - number of lines to be skipped in the sample. The output begins from skip +1 line (used for the pagination with the limit parameter, equals to 0 by default);
  • limit (optional - not taken into account when the parameter is cost_only) - the limit on the number of input lines (used for the pagination with the skip parameter, the maximum value is 1000, the default value is 1000).

Maximum period of getting statistics is - 1 month. If the limit in the request is exceeded, the time period automatically decreases to 30 days. If the start date is not specified, the start of the current month will be selected. If the end date is not specified, the current date and time will be selected.
Maximum number of input lines for one request - 1000. For pagination use the skip and limit parameters.

  • JSON
  • XML
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 13:45:23",
    "stats":[
        {
            "id":"155112249",
            "sip":"00001",
            "callstart":"2015-06-02 12:20:25",
            "from":442037691880,
            "to":442037691881,
            "description":"United Kingdom, London",
            "disposition":"busy",
            "billseconds":0,
            "cost":0.1950,
            "billcost":0.0000,
            "currency":"USD"
        },
        …
    ]
}
?type=cost_only:
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 14:03:57",
    "stats":[
        {
            "cost":38.094,
            "currency":"USD",
            "seconds":9785
        }
    ]
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2015-06-01 00:00:00</start>
    <end>2015-06-29 13:58:22</end>
    <stats>
        <value>
            <id>155112249</id>
            <sip>00001</sip>
            <callstart>2015-06-02 12:20:25</callstart>
            <description>United Kingdom, London</description>
            <disposition>busy</disposition>
            <billseconds>0</billseconds>
            <cost>0.195</cost>
            <billcost>0</billcost>
            <currency>USD</currency>
            <from>442037691880</from>
            <to>442037691881</to>
        </value>
        …
    </stats>
</answer>
?type=cost_only:
<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2015-06-01 00:00:00</start>
    <end>2015-06-29 14:03:30</end>
    <stats>
    <value>
        <cost>38.094</cost>
        <currency>USD</currency>
        <seconds>9785</seconds>
    </value>
    </stats>
</answer>

where

  • start – start date of the statistics display;
  • end – end date of the statistics display;
  • id – call ID;
  • sip – SIP-number;
  • callstart – the call start time;
  • description – description of call destination;
  • disposition – the call status:
    • 'answered' – conversation,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' - no answer,
    • 'failed' - failed,
    • 'no money' - no funds, the limit has been exceeded,
    • 'unallocated number' - the phone number does not exist,
    • 'no limit' - the limit has been exceeded,
    • 'no day limit' - the day limit has been exceeded,
    • 'line limit' - the line limit has been exceeded,
    • 'no money, no limit' - the limit has been exceeded;
  • billseconds – the amount of seconds;
  • cost – the cost per minute of calls to this destination;
  • billcost – the cost of the paid minutes;
  • currency – the cost currency;
  • from – which number was used to make a call;
  • to – the phone number that was called.

Parameters:

  • start - the start date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • end - the end date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • version - format of the statistics result (2 - new, 1 - old);
  • skip (optional) - number of lines to be skipped in the sample. The output begins from skip +1 line (used for the pagination with the limit parameter, equals to 0 by default);
  • limit (optional) - the limit on the number of input lines (used for the pagination with the skip parameter, the maximum value is 1000, the default value is 1000).
  • call_type (optional) - call destination ('in' for incoming, 'out' for outgoing). If not specified, all calls are displayed.
  • JSON
  • XML
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-30 23:59:59",
    "version":2,
    "stats":[
        {
            "call_id":1439981389.2702773,
            "sip":200,
            "callstart":"2015-06-01 15:04:00",
            "clid":200,
            "destination":5,
            "disposition":"answered",
            "seconds":5,
            "is_recorded":true,
            "pbx_call_id":"in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d"
        },
        …
    ]
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
        <start>2015-06-01 00:00:00</start>
        <end>2015-06-30 23:59:59</end>
        <version>2</version>
        <stats>
        <value>
            <call_id>1439981389.2702773</call_id>
            <sip>200</sip>
            <callstart>2015-06-01 15:04:00</date>
            <clid>200</clid>
            <destination>5</destination>
            <disposition>answered</disposition>
            <seconds>5</seconds>
            <is_recorded>true</is_recorded>
            <pbx_call_id>in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d</pbx_call_id>
        </value>
        …
    </stats>
</answer>

where

  • start – the start date of the statistics display;
  • end – the end date of the statistics display;
  • version - format of the statistics result (2 - new, 1 - old);
  • call_id – unique call ID, it is specified in the name of the file with the call recording (unique for every recording);
  • sip – SIP-number;
  • callstart – the call start time;
  • clid – CallerID;
  • destination – the call destination;
  • disposition – the call status:
    • 'answered' – conversation,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' - no answer,
    • 'failed' - failed,
    • 'no money' - no funds, the limit has been exceeded,
    • 'unallocated number' - the phone number does not exist,
    • 'no limit' - the limit has been exceeded,
    • 'no day limit' - the day limit has been exceeded,
    • 'line limit' - the line limit has been exceeded,
    • 'no money, no limit' - the limit has been exceeded;
  • seconds – the amount of seconds;
  • is_recorded – (true, false) recorded or no conversations;
  • pbx_call_id – permanent ID of the external call to the PBX (does not alter with the scenario changes, voice menu, etc., it is displayed in the statistics and notifications);

Parameters:

  • start - the start date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • end - the end date of the statistics display (format - YYYY-MM-DD HH:MM:SS);
  • widget_id - (optional) - widget identification; if the parameter is not specified, statistics from all widgets is taken;
Maximum period of getting the statistics is - 1 month. If the limit in the request is exceeded, the time period automatically decreases to 30 days. If the start date is not specified, the start of the current month will be selected. If the end date is not specified, the current date and time will be selected.
Maximum number of input lines for one request - 1000. For pagination use the skip and limit parameters.
  • JSON
  • XML
{
    "status":"success",
    "start":"2016-09-01 00:00:00",
    "end":"2016-09-30 23:59:59",
    "stats":[
        {
            "id":"57d16d6a1e46c53d1f8ce323",
            "widget_id":"1",
            "sip":"00001",
            "ip":"127.0.0.1",
            "actions":[
                {
                    "kind":"come",
                    "date":"2016-09-08 16:53:45",
                    "referrer_url":"http://test.domain.com/page1/",
                    "url":"http://home.domain.com/page2/"
                },
                {
                    "kind":"show",
                    "date":"2016-09-08 16:53:46",
                    "rate":15
                },
                {
                    "kind":"call_request",
                    "date":"2016-09-08 16:54:07",
                    "number":"442037691880",
                    "request_call_date":"2016-09-09 10:00:00",
                    "redial":"n"
                },
                {
                    "kind":"close",
                    "date":"2016-09-08 16:54:35"
                }
            ]
        },
        ...
    ]
}


<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2016-09-01 00:00:00</start>
    <end>2016-09-30 23:59:59</end>
    <stats>
        <value>
            <id>57d16d6a1e46c53d1f8ce323</id>
            <widget_id>1</widget_id>
            <sip>00001</sip>
            <ip>127.0.0.1</ip>
            <actions>
                <value>
                    <kind>come</kind>
                    <date>2016-09-08 16:53:45</date>
                    <referrer_url>http://test.domain.com/page1/</referrer_url>
                    <url>http://home.domain.com/page2/</url>
                </value>
                <value>
                    <kind>show</kind>
                    <date>2016-09-08 16:53:46</date>
                    <rate>15</rate>
                </value>
                <value>
                    <kind>call_request</kind>
                    <date>2016-09-08 16:54:07</date>
                    <number>442037691880</number>
                    <request_call_date>2016-09-09 10:00:00</request_call_date>
                    <redial>n</redial>
                </value>
                <value>
                    <kind>close</kind>
                    <date>2016-09-08 16:54:35</date>
                </value>
            </actions>
        </value>
            ...
    </stats>
</answer>

where

  • start – the start date of the statistics display;
  • end – the end date of the statistics display;
  • id – session ID;
  • widget_id – widget ID;
  • sip – SIP-number;
  • ip – user's IP-address;
  • kind – event type:
    • 'come' – the user visited the page with the widget,
    • 'show' – the widget form is displayed,
    • 'call' – CallBack request,
    • 'call_request' – delayed CallBack request,
    • 'rate' – the user rated the call,
    • 'fail' – the user reported that there was no CallBack,
    • 'close' – the user has closed the widget form;
  • date – the event date and time;
  • referrer_url – the URL address, from which the user came to the page with the widget(only for the event 'come');
  • url – the URL address of the widget page (only for the event 'come');
  • rate – for the event 'show' - number of points, for the event 'rate' - call rate;
  • request_call_date – the date and time for the CallBack specified by the user(only for the event 'call_request');
  • redial – (true, false) was there a CallBack for the delayed CallBack request (only for the event 'call_request');
  • number – the phone number entered by the user (for the events: 'call', 'call_request', 'rate', 'fail').

Parameters:

  • numbers – list of numbers for user database check in international format.

If numbers contain 1 number the result will be delivered immediately; if there is a list of numbers the result will be sent to the address specified on the user database check page or, if the address was not specified, to the email address.

Attention: to set up this method go to the user database check page in your personal account.

Example of the result for 1 number:


{
    "status":"success",
    "info":{
        'mcc' : '250',
        'mnc': '01',
        'mccName': 'Russia',
        'mncName': 'Mobile TeleSystems',
        'ported': false,
        'roaming': false,
        'errorDescription': 'No Error'
    }
}

Example of the result for several numbers:


{
    "status":"success"
}

Example of the result sent to the address specified on the user database check page:


{
    'success': true,
    'description': 'Проверено успешно',
    'result': [
        {
            'mcc': '250',
            'mnc': '01',
            'ported': false,
            'roaming': false,
            'errorDescription': 'No Error',
            'mccName': 'Russia',
            'mncName': 'Mobile TeleSystems',
            'number': '791234567890',
        }, ...
    ]
}

 

Incoming call notifications

Zadarma system can send information about each call to virtual PBX and route calls onto the necessary extension number depending on the response. In order to do this, create an open link, which will accept POST-requests with information from the Zadarma system.

Available methods:

  • NOTIFY_START
    the start of an incoming call in the PBX.
  • NOTIFY_INTERNAL
    the start of an incoming call to the PBX extension number.
  • NOTIFY_ANSWER
    the internal or external call response.
  • NOTIFY_END
    the end of an incoming call to the PBX extension number.
  • NOTIFY_OUT_START
    the start of an outgoing call from the PBX.
  • NOTIFY_OUT_END
    the end of an outgoing call from the PBX.
  • NOTIFY_RECORD
    the call recording is ready for download.
  • NOTIFY_IVR
    caller’s response to the assigned action.

Parameters that are sent to the link for notifications:

  • event – event (NOTIFY_START)
  • call_start – call start time;
  • pbx_call_id – call id;
  • caller_id – caller number;
  • called_did – number called.

Creating a verification signature for incoming calls notifications, PHP example:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['called_did'] . $_POST['call_start'], API_SECRET));

For requests NOTIFY_START and NOTIFY_IVR you can change the scenario for a current call “on the run” by responding with one of the following options:

Play a file:

{
    "ivr_play": "ID",
    "wait_dtmf": {...}
}

where,

  • ivr_play – the value of the ID column in the list of uploaded/input files for a needed file;
  • wait_dtmf – required parameter described below.

Play a popular:

{
    "ivr_saypopular": 1,
    "language": "en"
}

where,

  • ivr_saypopular – the number of the phrase on the list;

Play digits:

{
    "ivr_saydigits": "12",
    "language": "en"
}

Play a number (in accordance with the rules of complex numerals):

{
    "ivr_saynumber": "123",
    "language": "en"
}

где,

  • language can have one of the following values: ru, ua, en, es, pl;

If ivr_saydigits or ivr_saynumber were set, during the next NOTIFY_IVR event the following parameter will be added:

"ivr_saydigits": "COMPLETE" or "ivr_saynumber": "COMPLETE"

For each of the requests specified above a request to input digits from caller can occur:

{
    "wait_dtmf": {
        "timeout": TIMEOUT,
        "attempts": ATTEMPTS,
        "maxdigits": MAXDIGITS,
        "name": NAME,
        "default": DEFAULT,
    }
}

where,

  • timeout - wait time for digits input in seconds;
  • attempts - number of attempts of digits input from caller;
  • maxdigits - maximum number of digits that are expected to be input;
  • name - name that would be in the response;
  • default - an action if no digits were selected. Options:
    • redirection scenario id (in 0-1 format, where 0 is voice menu number, 1 is a scenario number);
    • PBX menu in 0-main format, where 0 is menu id;
    • PBX extension number (three digits);
    • hangup – end call.

During the next NOTIFY_IVR event an additional parameter will be specified:

{
  	"wait_dtmf": {
	    "name": NAME,
	    "digits": DIGITS,
	    "default_behaviour": "1"
    }
}

where,

  • name - name specified in the previous response;
  • digits - digits entered by the caller;
  • default_behaviour - specifies if the caller did not press any button and default behaviour worked;

Transfer call:

{
    "redirect": ID,
    "return_timeout": TIMEOUT (optional)
}

where,

  • redirect - redirect scenario id (in 0-1 format, where 0 is voice menu number, 1 is a scenario number); or in 1 format, where 1 is a scenario number(voice menu number is 0 in this case); or PBX menu in 0-main format, where 0 is menu id; or PBX extension number (three digits); or "blacklist" – in this case the call will be declined with a busy signal;
  • return_timeout - value in seconds. Options:
    • 0, call returns to the menu;
    • >= 3 – internal call duration before the call returns to the menu
  • default_behaviour - specified if the caller did not press anything and default behaviour worked;

End call:

{
    "hangup": 1
}

For each response you can additionally set:

A name for incoming number:

{
	"caller_name": NAME
}

where,

  • caller_name - caller name.

Lists of popular phrases:

Parameters glossary:

  • event – the event (NOTIFY_INTERNAL)
  • call_start – the call start time;
  • pbx_call_id – the call ID;
  • caller_id – the caller's phone number;
  • called_did – the phone number that was called;
  • internal – (optional) extension number.

Creation of verification signature for notification about incoming calls, example on PHP:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['called_did'] . $_POST['call_start'], API_SECRET));

Parameters glossary:

  • event – the event (NOTIFY_ANSWER)
  • caller_id – the caller's phone number;
  • destination – the phone number that was called;
  • call_start – the call start time;
  • pbx_call_id – the call ID;
  • internal – (optional) extension number.

Creation of verification signature for notification about incoming calls, example on PHP:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['destination'] . $_POST['call_start'], API_SECRET));

Parameters glossary:

  • event – the event (NOTIFY_END)
  • call_start – the call start time;
  • pbx_call_id – the call ID;
  • caller_id – the caller's phone number;
  • called_did – the phone number that was called;
  • internal – (optional) extension number;
  • duration – length in seconds;
  • disposition – call status:
    • 'answered' – conversation,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' - no answer,
    • 'failed' - failed,
    • 'no money' - no funds, the limit has been exceeded,
    • 'unallocated number' - the phone number does not exist,
    • 'no limit' - the limit has been exceeded,
    • 'no day limit' - the day limit has been exceeded,
    • 'line limit' - the line limit has been exceeded,
    • 'no money, no limit' - the limit has been exceeded;
  • status_code – call status code Q.931;
  • is_recorded – 1 - there is a call recording, 0 - there is no call recording;
  • call_id_with_rec – the ID of the call with call recording (we recommend you to download the recorded file in 40 seconds after the notification, as certain time period is needed for the file with the recording to be saved).

Creation of verification signature for notification about incoming calls, example on PHP:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['called_did'] . $_POST['call_start'], API_SECRET));

Parameters glossary:

  • event – the event (NOTIFY_OUT_START)
  • call_start – the call start;
  • pbx_call_id – the call ID;
  • destination – the phone number that was called;
  • internal – (optional) extension number.

Creation of verification signature for notification about incoming calls, example on PHP:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['internal'] . $_POST['destination'] . $_POST['call_start'], API_SECRET));

Parameters glossary:

  • event – the event (NOTIFY_OUT_END)
  • call_start – the call start time;
  • pbx_call_id – the call ID;
  • caller_id – the caller's phone number;
  • destination – the phone number that was called;
  • internal – (optional) extension number;
  • duration – length in seconds;
  • disposition – call status:
    • 'answered' – conversation,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' - no answer,
    • 'failed' - failed,
    • 'no money' - no funds, the limit has been exceeded,
    • 'unallocated number' - the phone number does not exist,
    • 'no limit' - the limit has been exceeded,
    • 'no day limit' - the day limit has been exceeded,
    • 'line limit' - the line limit has been exceeded,
    • 'no money, no limit' - the limit has been exceeded;
  • status_code – call status code Q.931;
  • is_recorded – 1 - there is a call recording, 0 - there is no call recording;
  • call_id_with_rec – the ID of the call with call recording (we recommend you to download the recorded file in 40 seconds after the notification, as certain time period is needed for the file with the recording to be saved).

Creation of verification signature for notification about incoming calls, example on PHP:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['internal'] . $_POST['destination'] . $_POST['call_start'], API_SECRET));

Parameters glossary:

  • event – the event (NOTIFY_RECORD)
  • call_id_with_rec – unique ID of the call with the call recording;
  • pbx_call_id – permanent ID of the external call to the PBX (does not alter with the scenario changes, voice menu, etc., it is displayed in the statistics and notifications).

Creation of verification signature for notification about incoming calls, example on PHP:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['pbx_call_id'] . $_POST['call_id_with_rec'], API_SECRET));

Parameters that are sent to the link for notifications:

  • event – event (NOTIFY_IVR)
  • call_start – call start time;
  • pbx_call_id – call id;
  • caller_id – caller number;
  • called_did – called number.

Creating a verification signature for incoming calls notifications, PHP example:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['called_did'] . $_POST['call_start'], API_SECRET));

Possible responses sent to similar responses as to NOTIFY_START requests

You can set the link for notifications and enable or disable each type of the notification in the API section of your personal profile.

In order for the link to be accepted by our system, it is necessary to add the verification code in the beginning of script.

PHP example:

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

For security reasons, we recommend you to allow access to your link only from the following IP: 185.45.152.42.

If you have issued the keys for access to the API, each request will receive an additional header "Signature", which can be used to compare data consistency and authenticity.

You can see a script example in our repository on GitHub.

Other notifications:

Parameter "result" in these notification is set in JSON format. You can receive it in XML format by entering parameter format=xml in the link.

  • NUMBER_LOOKUP
    number lookup report.
  • CALL_TRACKING
    information about calls to the numbers connected to call tracking.
  • SMS
    information about incoming SMS messages.

Parameters that are sent to the link for notifications:

  • event – event (NUMBER_LOOKUP)
  • success – successful lookup flag;
  • description – textual description of the lookup completion status;
  • result – report results;
    • number – number that is being checked;
    • mcc – mobile country code;
    • mnc – mobile network code;
    • ported – an indication that the number has been ported to another provider;
    • roaming – an indication that the number is currently in roaming zone;
    • error – error status indication;
    • errorDescription – textual description of the error;
    • mccName – country name;
    • mncName – provider name;

Creating a verification signature:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

It is sent out every 15 minutes, provided there are new calls.

Parameters that are sent to the link for notifications:

  • event – event (CALL_TRACKING)
  • result - array
    • tracker - ID tracker (can be found on the code installation page);
    • start - call starting time;
    • duration - call duration in seconds;
    • caller_id - caller’s number;
    • caller_did - the number that was called;
    • country - (optional) the country the call was made from;
    • ga_id - (optional, if Google Analytics ID is specified in the settings) Google Analytics ID of the visitor;
    • metrika_id - (optional, Yandex.Metrika ID is specified in the settings) Yandex.Metrika ID of the visitor;

Creating a verification signature:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

Parameters that are sent to link for notifications:

  • event – event (SMS)
  • result – array;
  • caller_id – senders number;
  • caller_did – receivers number;
  • text – message text.

Creating a verification signature:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));