API

Інтерфейс API від Zadarma дозволяє використовувати сервіс для власних додатків, а також для стикування з будь-якими CRM-системами та програмами для коллцентрів.

Реалізація API відкрита, з нею впорається будь-який розробник через невисокий ступінь складності.

В API доступні всі основні функції:

  • відображення і зміна налаштувань SIP та АТС;
  • відображення статистики та балансу;
  • відправка дзвінків (CallBack на зовнішні і внутрішні номери) та SMS-повідомлень;
  • повідомлення зовнішнього сервера про кожний вхідний дзвінок в АТС, а також зовнішня маршрутизація дзвінків.

Посилання на АПІ: https://api.zadarma.com

Версія АПІ: v1

Фінальне посилання на метод: https://api.zadarma.com/v1/METHOD/

Готовий клас PHP для роботи з API, можете завантажити з GitHub.

Авторизація

Кожен запит, який потребує авторизації, супроводжується додатковим заголовком, виду:

"Authorization: ключ_користувача: підпис"

Ключі для авторизації необхідно отримати у особистому кабiнетi.

Підпис складається за таким алгоритмом:

  • масив з переданих параметрів (GET, POST, PUT, DELETE) сортується за назвою ключа за алфавітом;
  • з отриманого масиву формується рядок запиту (наприклад, функція http_build_query in PHP), приклад "from=DATEFROM&to=DATETO…";
  • і далі - з'єднується за формулою:
    рядок = імя_метода строка_запроса md5 (строка_запроса),
    де "імя_метода" - рядок запиту, починаючи від домену (із зазначенням версії АПІ), до початку перерахування параметрів, наприклад - "/v1/sip/"
  • отриманий рядок кешируєтся за алгоритмом sha1 з секретним ключем користувача:
    hash = рядок, секретний_ключ
  • і далі хеш кодується в base64
    підпис = base64_encode( хеш )

Приклад на PHP:

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

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

Готовий клас PHP для роботи з API, можете завантажити на GitHub.

Формати відповіді: json (по-замовчуванню) і xml.

Щоб отримати відповідь від АПІ у форматі xml, в рядок запиту додається параметр "format=xml".

Restrictions

У відповіді також міститься інформація про ліміти і поточний запит, наприклад:

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

where,

  • X-Zadarma-Method – поточний викликається метод;
  • X-RateLimit-Remaining – кількість залишилися запитів, з урахуванням ліміту на метод і на користувача;
  • X-RateLimit-Limit – цифра загального ліміту звернень за хвилину;
  • X-RateLimit-Reset – час скидання ліміту.

Загальні обмеження - 100 запитів в хвилину, на методи статистики - 10 запитів в хвилину.

У разі блокування метод віддає відповідь з 429 заголовком "You exceeded the rate limit".

Відповідь складається з обов'язкового ключа "status" (success або error). Далі, залежно від методу, віддаються свої ключі з запитуваною інформацією.

У випадку помилки, віддається додатковий ключ "message" з описом помилки.

Також всі відповіді супроводжуються відповідними HTTP-заголовками.

Приклад відповіді помилки:
JSON:

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

XML:

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

Доступні методи:

GET /v1/info/balance/ - баланс користувача.

детальніше

Приклад відповіді:
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/ - вартість дзвінка з урахуванням поточного тарифу користувача.

детальніше

Параметри:
  • number – номер телефону
  • caller_id(опцiонально) – CallerID, який використовуватиметься при здійсненні дзвінка.
Приклад відповіді:
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/ - інформація про поточний тариф користувача.

детальніше

Приклад відповіді:
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>

де,

  • tariff_id – ID поточного тарифу користувача;
  • tariff_name – найменування поточного тарифу користувача;
  • is_active – активний або не активний поточний тариф;
  • cost – вартість тарифу;
  • currency – валюта тарифу;
  • used_seconds – кількість використаних секунд тарифу;
  • used_seconds_mobile – кількість використаних секунд тарифу на мобільні телефони;
  • used_seconds_fix – кількість використаних секунд тарифу на стаціонарні телефони;
  • tariff_id_for_next_period – ID тарифу користувача на наступний період;
  • tariff_for_next_period – найменування тарифу користувача на наступний період.

GET /v1/request/callback/ - запит на callback.

детальніше

Параметри:
  • from – ваш номер телефону, або SIP, або внутрішній номер АТС, або номер сценарію АТС, на який викликається callback;
  • to – номер телефону або SIP, якому дзвонять;
  • sip номер sip-користувача або внутрішній номер АТС (наприклад 100), через який йде дзвінок. Буде використаний CallerID цього номера, в статистиці відображатиметься даний номер SIP/АТС, якщо для вказаного номера включений запис дзвінків або префікси набору, вони також будуть задіяні;
  • predicted (опціонально) - якщо вказаний цей прапор, то запит є предикативним (система спочатку телефонує на номер "to" і тільки якщо йому додзвонюється, з'єднує з вашим SIP або телефонним номером);
Приклад відповіді:
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/ - список SIP-номерів користувача.

детальніше

Приклад відповіді:
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>

де,

  • id – SIP-id;
  • display_name – ім`я, що відображається;
  • lines – кількість ліній;
  • left – кількість SIP,що залишилися, які можна створити (залежить від балансу користувача та загальної кількості вже створених SIP).

GET /v1/sip/<SIP>/status/ - online-статус SIP-номера користувача.

детальніше

Приклад відповіді:
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>
    

де,

  • id – SIP-id;
  • is_online – online-статус (true|false);

PUT /v1/sip/callerid/ - зміна CallerID.

детальніше

Параметри:
  • id – SIP id, якому змінюють CallerID;
  • number – номер, на який змінюють у міжнародному форматі (зі списку підтверджених або придбаних номерів користувача).
Приклад відповіді:
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/ - відображення поточних переадресаций по SIP-номерам користувача.

детальніше

Параметри:
  • id – (опціональний) вибір конкретного SIP id.
Приклад відповіді:
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>

де,

  • sip_id – SIP id користувача;
  • status – поточний статус: on або off;
  • condition – умови переадресації: always - завжди (за замовчуванням), unavailable - в разі не підняття трубки або відсутності SIP-з'єднання;
  • destination – куди переадресовується: phone - на номер телефону, pbx - на АТС;
  • destination_value – номер, куди переадресовувати: номер телефону або ID АТС.

GET /v1/direct_numbers/ - інформація про прямі номери користувача.

детальніше

Приклад відповіді:
JSON:

{
    "status":"success",
    "info": [
        {
            "number":"442037691880",
            "status":"on",
            "country":"Великобританія",
            "description":"Лондон",
            "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>Великобританія</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>

Залежно від типа номера набір полів може відрізнятися! Опис полів:

  • number – куплений прямий номер користувача;
  • status – статус номера;
  • country – країна (для common і revenue);
  • description – опис: місто або тип (для common і revenue);
  • number_name – "ім'я" прямого номера (задається користувачем);
  • sip – SIP, прив'язаний до номера;
  • sip_name – "ім'я" SIP, прив'язаного до номера;
  • start_date – дата покупки номера користувачем;
  • stop_date – дата закінчення терміну оплати номера користувачем;
  • monthly_fee – вартість номера(для common);
  • currency – валюта вартості номера (для common);
  • channels – кількість ліній на номері (для common);
  • minutes – загальна тривалість вхідних дзвінків за поточний місяць (для revenue);
  • autorenew – чи включено автопродовження номера (для common, revenue, rufree);
  • is_on_test – чи знаходиться номер на тесті;
  • type – тип номера: common (прямий номер), inum (безкоштовний міжнародний номер), rufree (безкоштовний московський номер), revenue (безкоштовний московський номер 495)

GET /v1/sim/ - інформація про sim-карти користувача.

детальніше

Приклад відповіді:
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>

де,

  • iccid – ID SIM-карти;
  • name – "ім'я" SIM-карти;
  • sip – до якого SIP прив'язана карта;
  • phone_number – номер телефону карти;
  • redirect_to – куди перенаправлені вхідні дзвінки на карту (варіант: simcard, <номер телефону>);
  • status – поточний статус SIM-карти;
  • internet – відключений або включений інтернет.

PUT /v1/sip/redirection/ - включення/вимикання переадресації за номером SIP.

детальніше

Параметри:
  • id – SIP id;
  • status – статус переадресації, що виставляється, на обраний SIP-номер.
Приклад відповіді:
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/ - зміна параметрів переадресації.

детальніше

Параметри:
  • id – SIP id;
  • type – тип переадресації: phone - на телефон;
  • number – номер телефону.
Приклад відповіді:
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/ - вiдображення внутрiшнiх номерiв АТС.

детальніше

Приклад вiдповiдi:
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>

де,

  • pbx_id – id ATC користувача;
  • numbers – список внутрiшнiх номерiв.

GET /v1/pbx/internal/<PBXSIP>/status/ - online-статус внутрiшнього номеру АТС.

детальніше

Приклад вiдповiдi:
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 – АТС-id;
  • number – внутрiшнiй номер АТС;
  • is_online – online-статус (true|false).

PUT /v1/pbx/internal/recording/ - включення запису розмов на внутрiшнiм номерi АТС.

детальніше

Параметри:
  • id – внутрiшнiй номер АТС;
  • status – статус: "on" - увiмкнути, "off" - вимкнути;
  • email – (опцiнально) зміна електронної адреси, куди будуть відправлятися записи розмов. Ви можете зазначити до 3х електронних адрес через кому.
Приклад вiдповiдi:
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/ - запит на файл запису розмови.

детальніше

Параметри:
  • call_id – унікальний id дзвінка, цей id вказаний в назві файлу із записом розмови (унікальний для кожного запису в статистиці);
  • pbx_call_id – постійний ID зовнішнього дзвінка в АТС (не міняється при проходженні сценаріїв, голосового меню, transfer і так далі, відображається в статистиці і повідомленнях);
  • lifetime – (опціональний) время жизни ссылки в секундах (мінімум - 180, максимум - 5184000, за умовчанням - 1800).

Примітка: досить вказати один з двох параметрів ідентифікації (pbx_call_id або call_id), при вказівці pbx_call_id посилання відповідає на запит може бути декілька

Приклад відповіді коли вказаний лише call_id, посилання лише одно:
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>
    
Приклад відповіді коли вказаний лише pbx_call_id, посилань може бути декілька:
	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>
    

де,

  • link – посилання на файл розмови;
  • lifetime_till – до якого часу посилання працюватиме.

POST /v1/sms/send/ - відправка SMS.

детальніше

Параметри:
  • number – номер телефону, куди відправляти SMS (можна перелічити кілька через кому);
  • message – повідомлення (стандартні обмеження по довжині SMS, у разі перевищення ліміту - розбивається на кілька SMS);
  • caller_id – (опціональний) номер телефону, від кого буде відправлена ​​SMS (можна відправляти тільки зі списку підтверджених номерів користувача).

Зверніть увагу: відправлення SMS доступне тільки за межі РФ.

Приклад відповіді:
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/ - отримання загальної статистики.

детальніше

Параметри:
  • start - дата початку перегляду статистики (формат - Ymd H: i: s);
  • end - дата закінчення перегляду статистики (формат - Ymd H: i: s);
  • sip (опціонально) - фільтр за певним SIP-номером;
  • cost_only (опціонально) - перегляд тільки витрачених коштів за період;
  • type (опціонально - тільки на загальній статистиці) - тип запиту: загальний (не вказується в запиті), toll і ru495. (для статистики номерів 800 і безкоштовних номерів 495)

Максимальний період отримання статистики - місяць. У разі перевищення ліміту в запиті - період автоматично скорочується до 30 днів. Якщо не вказано дату початку вибірки, вибирається початок поточного місяця. Якщо не вказана дата кінця вибірки - вибірка обмежується поточною датою і часом.

Приклад відповіді:
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>

де,

  • start – дата початку відображення статистики;
  • end – дата закінчення відображення статистики;
  • id – id дзвінка;
  • sip – SIP-номер;
  • callstart – час початку дзвінка;
  • description – опис напрямку дзвінка;
  • disposition – стан дзвінка:
    • 'answered' – розмова,
    • 'busy' – зайнято,
    • 'cancel' - скасований,
    • 'no answer' – без відповіді,
    • 'failed' - не вдався,
    • 'no money' – немає коштів, перевищений ліміт,
    • 'unallocated number' – номер не існує,
    • 'no limit' – перевищений ліміт,
    • 'no day limit' – перевищений денний ліміт,
    • 'line limit' – перевищений ліміт ліній,
    • 'no money, no limit' - перевищений ліміт;
  • billseconds – кількість секунд дзвінка;
  • cost – вартість хвилини дзвінка по даному напрямку;
  • billcost – вартість оплачених хвилин;
  • currency – валюта вартості;
  • from – з якого номера телефонували;
  • to – куди дзвонили.
?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>

де,

  • cost – вартість дзвінків на вибраний період;
  • currency – валюта вартості;
  • seconds – кількість секунд.

GET /v1/statistics/pbx/ - статистика по АТС

детальніше

Параметри:
  • start - дата початку перегляду статистики (формат - Ymd H: i: s);
  • end - дата закінчення перегляду статистики (формат - Ymd H: i: s);
  • version - формат виведення статистики (2 - новий, 1 - старий);
Приклад відповіді:
JSON:

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

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

де,

  • start – дата початку відображення статистики;
  • end – дата закінчення відображення статистики;
  • version - формат виведення статистики (2 - новий, 1 - старий);
  • call_id – уникальний id дзвінка, цей id вказан у назві файлу з записом розмови (унікальний для кожного запису в статистиці);
  • sip – SIP-номер;
  • callstart – час початку дзвінка;
  • clid – CallerID;
  • description – опис напрямку дзвінка;
  • disposition – стан дзвінка:
    • 'answered' – розмова,
    • 'busy' – зайнято,
    • 'cancel' - скасований,
    • 'no answer' – без відповіді,
    • 'failed' - не вдався,
    • 'no money' – немає коштів, перевищений ліміт,
    • 'unallocated number' – номер не існує,
    • 'no limit' – перевищений ліміт,
    • 'no day limit' – перевищений денний ліміт,
    • 'line limit' – перевищений ліміт ліній,
    • 'no money, no limit' - перевищений ліміт;
  • seconds – кількість секунд у дзвінку;
  • is_recorded – (true, false) записана або нi розмова;
  • pbx_call_id – постійний ID зовнішнього дзвінка в АТС (не змінюється при проходжені сценаріїв, голосового меню, transfer і т.д., відображується у статистиці та повідомленнях);

GET /v1/statistics/callback_widget/ - статистика по Віджету зворотнього дзвінка

детальніше

Параметри:
  • start - дата початку перегляду статистики (формат - Y-m-d H:i:s);
  • end - дата закінчення перегляду статистики (формат - Y-m-d H:i:s);
  • widget_id - (опціонально) - ідентифікатор віджета, в разі відсутності параметра береться статистика по всім віджетам;

Максимальний період отримання статистики - місяць. У разі перевищення ліміту в запиті - період автоматично скорочується до 30 днів. Якщо не вказано дату початку вибірки, вибирається початок поточного місяця. Якщо не вказана дата кінця вибірки - вибірка обмежується поточною датою і часом.

Приклад відповіді:
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>    
    

де,

  • start – дата початку відображення статистики;
  • end – дата закінчення відображення статистики;
  • id – id сесії;
  • widget_id – id віджета;
  • sip – SIP-номер;
  • ip – IP-адреса відвідувача;
  • kind – тип події:
    • 'come' – відвідувач прийшов на сторінку з віджетом,
    • 'show' – показана форма віджета,
    • 'call' – замовлення зворотнього дзвінка,
    • 'call_request' – замовлення відкладеного зворотнього дзвінка,
    • 'rate' – відвідувач оцінив розмову,
    • 'fail' – відвідувач зазначив, що зворотнього дзвінка не було,
    • 'close' – відвідувач закрив форму віджета;
  • date – дата і час події;
  • referrer_url – адреса сторінки, з якої відвідувач прийшов на сторінку з віджетом (тільки для події 'come');
  • url – адреса сторінки віджета (тільки для події 'come');
  • rate – для події 'show' - кількість набраних очок, для події 'rate' - оцінка розмови;
  • request_call_date – дата і час вказане відвідувачем, як зручне для зворотнього дзвінка (тільки для події 'call_request');
  • redial – (true, false) подзвонили чи ні у відповідь на замовлення відкладеного зворотнього дзвінка (тільки для події 'call_request');
  • number – номер введений відвідувачем (для подій 'call', 'call_request', 'rate', 'fail').

Інформація про вхідні дзвінки

Система Zadarma може відправляти інформацію по кожному вхідному дзвінку в віртуальній АТС і направляти дзвінок на потрібний внутрішній номер залежно від відповіді. Для цього необхідно створити відкрите для загального доступу посилання, яке буде приймати POST-запити з інформацією з системи Zadarma.

Існуючі типи повідомлень:

NOTIFY_START - початок вхідного дзвінка в АТС.

детальніше

Параметри, які відправляються на посилання для повідомлень:

  • event – подія (NOTIFY_START)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • caller_id – номер того, хто дзвонить;
  • called_did – номер, на який подзвонили.

NOTIFY_INTERNAL - початок вхідного дзвінка на внутрішній номер АТС.

детальніше

Параметри, які відправляються на посилання для повідомлень:

  • event – подія (NOTIFY_INTERNAL)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • caller_id – номер того, хто дзвонить;
  • called_did – номер, на який подзвонили;
  • internal – (опціональний) внутрішній номер.

NOTIFY_END - кінець вхідного дзвінка на внутрішній номер АТС.

детальніше

Параметри, які відправляються на посилання для повідомлень:

  • event – подія (NOTIFY_END)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • caller_id – номер того, хто дзвонить;
  • called_did – номер, на який подзвонили;
  • internal – (опціональний) внутрішній номер;
  • duration – тривалість в секундах;
  • disposition – стан дзвінка:
    • 'answered' – розмова,
    • 'busy' – зайнято,
    • 'cancel' - скасований,
    • 'no answer' – без відповіді,
    • 'failed' - не вдався,
    • 'no money' – немає коштів, перевищений ліміт,
    • 'unallocated number' – номер не існує,
    • 'no limit' – перевищений ліміт,
    • 'no day limit' – перевищений денний ліміт,
    • 'line limit' – перевищений ліміт ліній,
    • 'no money, no limit' - перевищений ліміт;
  • status_code – код статусу дзвінка Q.931;
  • is_recorded – 1 - є запис дзвінка, 0 - немає запису;
  • call_id_with_rec – id дзвінка із записом.

NOTIFY_OUT_START - початок вихідного дзвінка з АТС.

детальніше

Параметри, які відправляються на посилання для повідомлень:

  • event – подія (NOTIFY_OUT_START)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • destination – номер, на який подзвонили;
  • internal – (опціональний) внутрішній номер.

NOTIFY_OUT_END - кінець вихідного дзвінка з.

детальніше

Параметри, які відправляються на посилання для повідомлень:

  • event – подія (NOTIFY_OUT_END)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • caller_id – номер того, хто дзвонить;
  • destination – номер, на який подзвонили;
  • internal – (опціональний) внутрішній номер;
  • duration – тривалість в секундах;
  • disposition – стан дзвінка:
    • 'answered' – розмова,
    • 'busy' – зайнято,
    • 'cancel' - скасований,
    • 'no answer' – без відповіді,
    • 'failed' - не вдався,
    • 'no money' – немає коштів, перевищений ліміт,
    • 'unallocated number' – номер не існує,
    • 'no limit' – перевищений ліміт,
    • 'no day limit' – перевищений денний ліміт,
    • 'line limit' – перевищений ліміт ліній,
    • 'no money, no limit' - перевищений ліміт;
  • status_code – код статусу дзвінка Q.931;
  • is_recorded – 1 - є запис дзвінка, 0 - немає запису;
  • call_id_with_rec – id дзвінка із записом.

Задати посилання за яким повідомляти, а також включити/виключити кожен вид повідомлень, ви можете в розділі API особистого кабінету.

Для того, щоб система прийняла посилання, необхідно додати код перевірки на початку скрипта.

Приклад на PHP:

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

Для збільшення безпеки, рекомендуємо дозволити доступ до вашого посилання тільки з IP 185.45.152.42.

Також, якщо Ви випустили ключі для доступу до API, в кожному запиті на ваше посилання буде приходити додатковий заголовок "Signature", за яком також є змога звіряти цілісність, а також достеменність даних.

Складання перевірочного підпису, приклад на PHP:

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

Для кожного запиту можна «на льоту» змінювати сценарій роботи з поточного дзвінка, відправивши у відповідь на інформацію:

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

де,

  • redirect – id сценарію редиректу або внутрішній номер АТС;
  • caller_name – можна дати ім'я вхідному номеру.

Максимальний час відповіді з інформацією про редірект і імені номера - до 2 секунд.

Приклад скрипту можете подивитися на нашому репозиторії на GitHub.