API

API interface from Zadarma allows to use service for own applications and also for integration with any CRM systems and softphones for call centers.

API is very simple to use and every developer can handle it.

In API are available all main functions:

  • Displaying and changing of settings for SIP and PBX;
  • Displaying of statistics and balance;
  • Calls and SMS (CallBack on external and internal numbers);
  • Notification for external server about every incoming call and also external routing of 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 needs authorization, sends with additional header like:

"Authorization: user_key: signature"

Keys for authorization must be received in personal account.

Signature is made by following algorithm:

  • Array of transmitted data (GET, POST, PUT, DELETE) is sorted by name of key in alphabetical order;
  • From received array request line is formed (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 domain (with indication of API version) till beginning of 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 response from API in xml format, in request line is added parameter "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 – digit of total limit 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 key "status" (success or error). Further, depending on method, own 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/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 или call_id)

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

    

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 calls on virtual PBX and route call on needed internal number depending on response. For that is needed to create a link, open for everyone, which will accept POST-requests with information from Zadarma system.

Existing types of notifications:

NOTIFY_START - start of incoming call in PBX.

details

Parameters which are sent on link for notifications:

  • event – event (NOTIFY_START)
  • call_start – 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

Parameters which are sent on link for notifications:

  • event – event (NOTIFY_INTERNAL)
  • call_start – 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

Parameters which are sent on link for notifications:

  • event – event (NOTIFY_END)
  • call_start – 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;
  • reason – cause of failed call (All possible variants of answer: "CHANUNAVAIL", "CONGESTION", "NOANSWER", "BUSY", "ANSWER", "CANCEL");
  • 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.

NOTIFY_OUT_START - start of outgoing call from PBX.

details

Parameters which are sent on link for notifications:

  • event – event (NOTIFY_OUT_START)
  • call_start – 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

Parameters which are sent on link for notifications:

  • event – event (NOTIFY_OUT_END)
  • call_start – 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;
  • reason – cause of failed call (All possible variants of answer: "CHANUNAVAIL", "CONGESTION", "NOANSWER", "BUSY", "ANSWER", "CANCEL");
  • 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.

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

In order link to be accepted by our system is needed to add 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 to allow access to your link only from IP 185.45.152.42.

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

Creation of verification signature, example on PHP:

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

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

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

where,

  • redirect – scenario id of redirect or PBX internal number, "blacklist" - in this case a call will be rejected with the busy tone;
  • 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.

A script example you can see in our repository on GitHub.