API

API interface from Zadarma allows the user to use our service for personal applications and also for integration with any CRM system and softphones for call centers.

API is very simple to use and every developer would be up for the task.

The following functions are available in API:

  • Displaying and changing of settings for SIP and PBX;
  • Displaying statistics and balance;
  • Calls and SMS (CallBack to internal and external numbers);
  • External server notifications regarding every incoming call and also external routing of the call.

Link for API: https://api.zadarma.com

API version: v1

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

Predefined class PHP for work with API, you can download it on GitHub.

Authorization

Each request, which requires authorization, is sent with the additional header:

"Authorization: user_key: signature"

Keys for authorization must be received on personal account.

Signature is made by following algorithm:

  • Array of transmitted data (GET, POST, PUT, DELETE) is sorted by key name in alphabetical order;
  • Request line is formed from received array (for example, function http_build_query in PHP), example "from=DATEFROM&to=DATETO…";
  • And further – summed by formula:
    line = method_name request_line md5(request_line),
    where " method_name " is request line beginning from the domain (with indication of API version) till the beginning of the parameters list, for example - /v1/sip/"
  • Gotten line is cashed by algorithm sha1 with user secret key:
    hash = line, secret key
  • And then hash is encrypted in base64
    signature = base64_encode( hash )

Example on PHP:

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

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

The complete PHP class for Zadarma API you can download on GitHub.

Response formats: json (by default) and xml.

In order to get the response from API in xml format, the following parameter is added to request line "format=xml".

Restrictions

Response also contains information about limits and 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 – quantity of requests left including limit on method and user;
  • X-RateLimit-Limit – number of total limits of requests per minute;
  • X-RateLimit-Reset – limit reset time.

Common limits - 100 requests per minute, on statistics methods - 10 requests per minute.

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

Response consists of compulsive keys "status" (success or error). After, depending on method, corresponding keys are provided with requested information.

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

Also all responses are provided with corresponding HTTP-headers.

Example of 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:

GET /v1/info/balance/ - user balance.

read more

Example:
JSON:

{
    "status":"success",
    "balance":10.34,
    "currency":"USD"
}

XML:

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

GET /v1/info/price/ - call rate in user's current tariff plan.

read more

Parameters:
  • number – phone number
  • caller_id (optionally) – CallerID, which will be used for outgoing call.
Example:
JSON:

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

XML:

<?xml version="1.0"?>
<answer>
<status>success</status>
    <info>
        <prefix>420</prefix>
        <description>United Kingdom, London</description>
        <price>0.009</price>
        <currency>USD</currency>
    </info>
</answer>

GET /v1/info/timezone/ - user timezone.

read more

Example:
JSON:

    {
        "status":"success",
        "unixtime":1483228800,
        "datetime":"2017-01-01 00:00:00",
        "timezone":"UTC+0"
    }

    XML:

    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <unixtime>1483228800</unixtime>
        <datetime>2017-01-01 00:00:00</datetime>
        <timezone>UTC+0</timezone>
    </answer>

GET /v1/tariff/ - information about current tariff plan of user.

read more

Answer example:
JSON:

{
    "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:

    <?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 – ID of current tariff plan of user;
  • tariff_name – name of current tariff plan of user;
  • is_active – active or not active current tariff plan;
  • cost – tariff plan price;
  • currency – tariff plan currency;
  • used_seconds – amount of used seconds in tariff plan;
  • used_seconds_mobile – amount of used seconds in tariff plan on mobile numbers;
  • used_seconds_fix – amount of used seconds in tariff plan on landline numbers;
  • tariff_id_for_next_period – ID of tariff plan of user for next period;
  • tariff_for_next_period – name of tariff plan of user on next period.

GET /v1/request/callback/ - callback request.

read more

Parameters:
  • from – your phone number, or sip number, or internal number of IP PBX, or call scenario of IP PBX, on which callback is requested;
  • to – phone number or SIP number, which is called;
  • sip (optionally) – user SIP number or internal number of IP PBX (for example 100), from which will be call made. CallerID of this number will be used, in statistics will be displayed given SIP number or number of IP PBX, if for that number call recording option or prefixes for outgoing calls are enabled, they will be also used;
  • predicted (optional) – if flag put down, then request is predictive (system calls on number "to" and if call is answered it joins with your SIP or phone number);
Example:
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>

GET /v1/sip/ - list of user's SIP-numbers.

read more

Example:
JSON:

{
    "status":"success",
    "sips":[
        {
            "id":"00001",
            "display_name":"SIP 1",
            "lines":3
        },
        {
            "id":"00002",
            "display_name":"SIP 2",
            "lines":3
        }
    ],
    "left":3
}

XML:

    <?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 – amount of lines;
  • left – amount of SIP which can be added (depends on user's balance and total amount of already added SIP).

GET /v1/sip/<SIP>/status/ - online-status of user SIP login.

details

Example of answer:
JSON:

    {
        "status":"success",
        "sip":"00001",
        "is_online":"false"
    }

    XML:

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

where,

  • id – SIP-id;
  • is_online – online-status (true|false);

PUT /v1/sip/callerid/ - changing of CallerID.

read more

Parameters:
  • id – SIP id, on which CallerID is changed;
  • number – phone number in international format to which is (from the list of confirmed or ordered user's).
Example:
JSON:

{
    "status":"success",
    "sip":"00001",
    "new_caller_id":"442037691880"
}

XML:

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

GET /v1/sip/redirection/ - displaying of current call forwarding on user's SIP-numbers.

read more

Parameters:
  • id – (optional) chooses definite SIP id.
Example:
JSON:
{
    "status":"success",
    "info": [
        {
            "sip_id":"00001",
            "status":"on",
            "condition":"always",
            "destination":"phone",
            "destination_value":"442037691880",
        },
        ...
    ]
}

XML:

<?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 – user's SIP id;
  • status – current status: on or off;
  • condition – conditions of call forwarding: always – always (by default), unavailable – in case of absence of answer or SIP connection;
  • destination – to where is forwarded: phone – on phone number, pbx – on PBX;
  • destination_value – number on which to forward: phone number or PBX ID.

GET /v1/direct_numbers/ - information about phone numbers (DID) of user.

read more

Answer example:
JSON:

{
    "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:

    <?xml version="1.0"?>
    <answer>
    <status>success</status>
    <info>
        <value>
            <number>442037691880</number>
            <status>on</status>
            <country>Great Britain</country>
            <description>London</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>

Depending on type of number, set of fields can vary.! Fields description:

  • number – connected by user phone number;
  • status – status of number;
  • country – country (for common and revenue);
  • description – description: city or type (for common and revenue);
  • number_name – "name" of phone number (set by user);
  • sip – SIP, connected to number;
  • sip_name – "name" of SIP, connected to number;
  • start_date – date when user connected number;
  • stop_date – date when user should pay for number;
  • monthly_fee – cost for number (for common);
  • currency – currency in which number is paid (for common);
  • channels – amount of channels on number (for common);
  • minutes – total duration of incoming calls for current month (for revenue);
  • autorenew – enabled or not autoprolongation for number (for common, revenue, rufree);
  • is_on_test – number is on test or not;
  • type – three numbers: common (phone number), inum (free international number), rufree (free Russian number), revenue (free Moscow number in code 495)

GET /v1/sim/ - information about SIM-cards of user.

read more

Example of answer:
JSON:

{
    "status":"success",
    "sims": [
        {
            "iccid":"8923416550000723980",
            "name":"My Sim",
            "sip":"00001",
            "phone_number":" 447978027321",
            "redirect_to":"simcard",
            "status":"enabled",
            "internet":"on"
        },
        ...
    ]
}

XML:

    <?xml version="1.0"?>
    <answer>
    <status>success</status>
    <sims>
        <value>
            <iccid>8923416550000723980</iccid>
            <name>My Sim</name>
            <sip>00001</sip>
            <phone_number> 447978027321</phone_number>
            <redirect_to>simcard</redirect_to>
            <status>enabled</status>
            <internet>on</internet>
        </value>
        ...
    </sims>
    </answer>

where,

  • iccid – SIM-card ID;
  • name – SIM-card "name";
  • sip – to which SIP login is connected card;
  • phone_number – card phone number;
  • redirect_to – to where incoming calls on card are forwarded (variant: simcard, phone number);
  • status – current status of SIM-card;
  • internet – enabled/disabled Internet connection.

PUT /v1/sip/redirection/ - able/disable of forwarding by sip.

read more

Parameters:
  • id – SIP id;
  • status – set status of forwarding on chosen SIP-number.
Example:
JSON:

{
    "status":"success",
    "sip":"00001",
    "current_status":"on"
}

XML:

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

PUT /v1/sip/redirection/ - changing parameters of forwarding.

read more

Parameters:
  • id – SIP id;
  • type – type of forwarding: phone – on phone;
  • number – phone number.
Example:
JSON:

{
    "status":"success",
    "sip":"00001",
    "destination":"442037691880"
}

XML:

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

GET /v1/pbx/internal/ - map PBX internal numbers.

read more

Example:
JSON:
{
    "status":"success",
    "pbx_id":1234,
    "numbers": [
        100,
        101,
        ...
    ]
}

XML:

<?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 – id PBX user;
  • numbers – a list of internal numbers.

GET /v1/pbx/internal/<PBXSIP>/status/ - PBX inner number online-status.

read more

Example:
JSON:
    {
        "status":"success",
        "pbx_id":1234,
        "number":100,
        "is_online":"false"
    }

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

де,

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

PUT /v1/pbx/internal/recording/ - the inclusion of call recording to an internal PBX.

read more

Options:
  • id – internal PBX number;
  • status – status: "on" - switch on, "off" - switch off;
  • email – (optional) change your email address, which will be sent to record conversations. You can specify up to 3 email addresses separated by comma.
Example:
JSON:

{
    "status":"success",
    "internal_number":100,
    "recording":"on",
    "email":"test@test.com"
}

XML:

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

GET /v1/pbx/record/request/ - request on call recording file.

read more

Parameters:
  • call_id – unique id of the call, Id listed in the title of the call recording file (is unique for each of the records);
  • pbx_call_id – permanent ID for the external call through PBX (is not changing during the passage of scripts, IVR, transfer etc., displayed in statistics and notifications);
  • lifetime – (optional) lifetime of link in seconds (minimal - 180, maximal - 5184000, by default - 1800).

Note: it's enough to specify one of two parameters of identification (pbx_call_id or call_id), if pbx_call_id is specified then in response on request can be several links

Example of response when only call_id is specified, only one link:
JSON:

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

    XML:

    <?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>
Example of response when only pbx_call_id is specified, might be several links:
	JSON:
    {
        "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"
    }

    XML:
    <?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>

where,

  • link – link on file with call recording;
  • lifetime_till – time till which link will be active.

POST /v1/sms/send/ - SMS sending.

read more

Parameters:
  • number – phone number, on which to send SMS (can be listed several separated by a comma);
  • message – message (standard text limits in SMS, in case if limit is exceeded – splits on several SMS);
  • caller_id – (optional) phone number, from whom SMS is sent (can be sent only from list of user's confirmed numbers).

Note: SMS sending is not available to Russian Federation.

Example:
JSON:

{
    "status":"success",
    "messages":1,
    "cost":0.24,
    "currency":"USD"
}

XML:

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

GET /v1/statistics/ - get common statistics.

read more

Parameters:
  • start - start date to view (format - Y-m-d H:i:s);
  • end - end date to view (format - Y-m-d H:i:s);
  • sip (optional) - filter by specific SIP-number;
  • cost_only (optional) – review of only spent funds for period;
  • type (optional – only for common statistics) – type of request: common (not specified in request), toll and ru495. (for numbers 800 and free 495 statistics)

Maximal period of getting statistics is 30 days. In case limit is exceeded in request time period will be shortened to 30 days. If start date is not specified, beginning of current month will be chosen. If end date is not specified, request is limited by current date and time.

Example:
JSON:

{
    "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"
        },
        …
    ]
}

XML:

<?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>

where,

  • start – start date of statistics displaying;
  • end – end date of statistics displaying;
  • id – call id;
  • sip – SIP-number;
  • callstart – time of call start;
  • description – description of call destination;
  • disposition – call status:
    • 'answered' – answerer,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' – no answer,
    • 'failed' - failed,
    • 'no money' – no funds, limit is exceeded,
    • 'unallocated number' – the number doesn't exist,
    • 'no limit' – limit is exceeded,
    • 'no day limit' – day limit exceeded,
    • 'line limit' – line limit is exceeded,
    • 'no money, no limit' - limit is exceeded;
  • billseconds – amount of seconds;
  • cost – rate for one minute of call on this destination;
  • billcost – cost of paid minutes;
  • currency – cost currency;
  • from – from which number call was made;
  • to – to which number call was made.
?type=cost_only:
JSON:

{
    "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:

<?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,

  • cost – cost of calls for chosen period;
  • currency – cost currency;
  • seconds – amount of seconds.

GET /v1/statistics/pbx/ - PBX statistics

read more

Parameters:
  • start - start date to view statistic (format - Y-m-d H:i:s);
  • end - end date to view statistic (format - Y-m-d H:i:s);
  • version - data format of statistics leading out (2 - new, 1 - old);
Example
JSON:

{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-30 23:59:59",
    "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:

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2015-06-01 00:00:00</start>
    <end>2015-06-30 23:59:59</end>
    <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 – start date of statistics displaying;
  • end – end date of statistics displaying;
  • version - data format of statistics leading out (2 - new, 1 - old);
  • call_id – call id;
  • sip – SIP-number;
  • callstart – time of call start;
  • clid – CallerID;
  • destination – call destination;
  • disposition – call status:
    • 'answered' – answerer,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' – no answer,
    • 'failed' - failed,
    • 'no money' – no funds, limit is exceeded,
    • 'unallocated number' – the number doesn't exist,
    • 'no limit' – limit is exceeded,
    • 'no day limit' – day limit exceeded,
    • 'line limit' – line limit is exceeded,
    • 'no money, no limit' - limit is exceeded;
  • seconds – number of seconds in call;
  • is_recorded – (true, false) recorded or not;
  • pbx_call_id – permanent ID for the external call through PBX (is not changing during the passage of scripts, IVR, transfer etc., displayed in statistics and notifications);

GET /v1/statistics/callback_widget/ - Callback widget statistics

read more

Parameters:
  • start - start date to view statistic (format - Y-m-d H:i:s);
  • end - end date to view statistic (format - Y-m-d H:i:s);
  • widget_id - (optional) - widget identificator, in case of absence of parameter is taken statistics for all widgets;

Maximal period of getting statistics is 30 days. In case limit is exceeded in request time period will be shortened to 30 days. If start date is not specified, beginning of current month will be chosen. If end date is not specified, request is limited by current date and time.

Example:
JSON:

    {
        "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:

    <?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 – start date of statistics displaying;
  • end – end date of statistics displaying;
  • id – session id;
  • widget_id – widget id;
  • sip – SIP-number;
  • ip – user IP-address;
  • kind – event type:
    • 'come' – user came on page with widget,
    • 'show' – shown widget form,
    • 'call' – callback request,
    • 'call_request' – delayed callback request,
    • 'rate' – user rated call,
    • 'fail' – user reported that callback failed,
    • 'close' – user closed widget form;
  • date – date and time of event;
  • referrer_url – URL, from which user came on page with wodget (only for event 'come');
  • url – URL of page with widget (only for event 'come');
  • rate – for event 'show' - amount of points, for event 'rate' - call rate;
  • request_call_date – date and time specified by user as convenient for callback (only for event 'call_request');
  • redial – (true, false) was there a callback for delayed callback request (only for event 'call_request');
  • number – number entered by user (for events 'call', 'call_request', 'rate', 'fail').

Information about incoming calls

Zadarma system can send information about each incoming call on virtual PBX and route call on the necessary internal number depending on the response. In order to apply, create a link open to everyone, which will accept POST-requests with information from the Zadarma system.

Existing types of notifications:

NOTIFY_START - start of incoming call in PBX.

details

Glossary of Parameters:

  • event – event (NOTIFY_START)
  • callstart – call start time;
  • pbx_call_id – call id;
  • caller_id – calling party number;
  • called_did – called party number.

NOTIFY_INTERNAL - start of incoming call on internal number of PBX.

details

Glossary of Parameters:

  • event – event (NOTIFY_INTERNAL)
  • callstart – call start time;
  • pbx_call_id – call id;
  • caller_id – calling party number;
  • called_did – called party number;
  • internal – (optional) internal number.

NOTIFY_END - end of incoming call on internal number of PBX.

details

Glossary of Parameters:

  • event – event (NOTIFY_END)
  • callstart – call start time;
  • pbx_call_id – call id;
  • caller_id – calling party number;
  • called_did – called party number;
  • internal – (optional) internal number;
  • duration – duration in seconds;
  • disposition – call status:
    • 'answered' – answerer,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' – no answer,
    • 'failed' - failed,
    • 'no money' – no funds, limit is exceeded,
    • 'unallocated number' – the number doesn't exist,
    • 'no limit' – limit is exceeded,
    • 'no day limit' – day limit exceeded,
    • 'line limit' – line limit is exceeded,
    • 'no money, no limit' - limit is exceeded;
  • status_code – call status code Q.931;
  • is_recorded – 1 - call recording is available, 0 - no call recording;
  • call_id_with_rec – call id with recording (it will take up to 40 seconds for your file to be saved. We recommend you to wait for a minute before downloading it).

NOTIFY_OUT_START - start of outgoing call from PBX.

details

Glossary of Parameters:

  • event – event (NOTIFY_OUT_START)
  • callstart – call start time;
  • pbx_call_id – call id;
  • destination – number on which call was made;
  • internal – (optional) internal number.

NOTIFY_OUT_END - end of outgoing calla from PBX.

details

Glossary of Parameters:

  • event – event (NOTIFY_OUT_END)
  • callstart – call start time;
  • pbx_call_id – call id;
  • caller_id – calling party number;
  • destination – number on which call was made;
  • internal – (optional) internal number;
  • duration – duration in seconds;
  • disposition – call status:
    • 'answered' – answerer,
    • 'busy' – busy,
    • 'cancel' - cancelled,
    • 'no answer' – no answer,
    • 'failed' - failed,
    • 'no money' – no funds, limit is exceeded,
    • 'unallocated number' – the number doesn't exist,
    • 'no limit' – limit is exceeded,
    • 'no day limit' – day limit exceeded,
    • 'line limit' – line limit is exceeded,
    • 'no money, no limit' - limit is exceeded;
  • status_code – call status code Q.931;
  • is_recorded – 1 - call recording is available, 0 - no call recording;
  • call_id_with_rec – call id with recording (it will take up to 40 seconds for your file to be saved. We recommend you to wait for a minute before downloading it).

NOTIFY_RECORD - call recording is ready for download.

show more

Glossary of Parameters:

  • event – event (NOTIFY_RECORD)
  • call_id_with_rec – call unique ID with recording;
  • pbx_call_id – PBX outgoing call permanent ID (does not change with change of scenarios, voice menu, forwarding, etc., displayed in statistics and notifications).

Set link for notifications, switch on/off each type of notification you can in personal account, section API.

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

Example on PHP:

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

For security reasons we recommend allowing access to your link only from IP 185.45.152.42.

Also if you issued keys for access to API, each request on your link will be sent an additional header "Signature", by which you can compare data consistency and integrity.

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

For NOTIFY_OUT_START and NOTIFY_OUT_END:

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

For NOTIFY_RECORD:

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

For NOTIFY_START request you can easily change work scenario for current call by sending in the response on information:

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

where,

  • redirect - redirect scenario ID (in 0-1 format where 0 serves as the voice menu number and 1 is the number of the scenario) or internal PBX number, "blacklist" - in this case the call will be declined with a busy signal;
  • caller_name – name of incoming number can be set.

Maximal time of response with information about redirection and number's name is up to 2 seconds.

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