API

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

Реализация API открыта, с ней справится любой разработчик по причине невысокой степени сложности.

В API доступны все основные функции:

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

Ссылка на АПИ: https://api.zadarma.com

Версия АПИ: v1

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

Скачайте готовые классы PHP, Python для работы с API на нашем GitHub.

Авторизация

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

"Authorization: ключ_пользователя: подпись"

Ключи для авторизации необходимо получить в личном кабинете.

Подпись составляется по следующему алгоритму:

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

Пример на PHP:

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

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

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

Форматы ответа: json (по-умолчанию) и xml.

Чтобы получить ответ от АПИ в формате xml, в строку запроса добавляется параметр "format=xml".

Ограничения

В ответе также содержится информация о лимитах и текущем запросе, например:

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

где,

  • 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 (опционально) – 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/info/timezone/ - часовой пояс пользователя.

подробнее

Пример ответа:
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/ - информация о текущем тарифе пользователя.

подробнее

Пример ответа:
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/ - отображение внутренних номеров АТС.

подробнее

Пример ответа:
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 – список внутренних номеров.

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

подробнее

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

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

подробнее

Параметры:
  • id – внутренний номер АТС;
  • status – статус: "on" - включить, "off" - отключить, "on_email" - включить только запись на почту, "off_email" - отключить только запись на почту, "on_store" - включить только запись в хранилище, "off_store" - отключить только запись в хранилище;
  • email – (опциональный) изменение электронного адреса, куда будут отправляться записи разговоров. Вы можете указать до 3х email адресов через запятую.
Пример ответа:
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 - дата начала просмотра статистики (формат - Y-m-d H:i:s);
  • end - дата окончания просмотра статистики (формат - Y-m-d 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 - дата начала просмотра статистики (формат - Y-m-d H:i:s);
  • end - дата окончания просмотра статистики (формат - Y-m-d 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;
  • destination – куда звонили;
  • 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) записан или нет разговор;
  • 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_ANSWER - ответ при звонке на внутренний или на внешний номер.

подробнее

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (NOTIFY_ANSWER)
  • caller_id – номер звонящего;
  • destination – номер, на который позвонили;
  • call_start – время начала звонка;
  • pbx_call_id – id звонка;
  • 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 звонка с записью (рекомендуем загружать файл записи не ранее чем через 40 секунд после уведомления т.к. для сохранения файла записи нужно время).

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 звонка с записью (рекомендуем загружать файл записи не ранее чем через 40 секунд после уведомления т.к. для сохранения файла записи нужно время).

NOTIFY_RECORD - запись звонка готова для скачивания.

подробнее

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (NOTIFY_RECORD)
  • call_id_with_rec – уникальный id звонка с записью разговора;
  • pbx_call_id – постоянный ID внешнего звонка в АТС (не меняется при прохождении сценариев, голосового меню, transfer и т.д., отображается в статистике и уведомлениях).

Задать ссылку по которой уведомлять, а также включить/выключить каждый вид уведомлений вы можете в разделе 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));

Для NOTIFY_OUT_START и NOTIFY_OUT_END:

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

Для NOTIFY_RECORD:

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

Для NOTIFY_ANSWER:

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

Для запроса NOTIFY_START можно «на лету» изменять сценарий работы по текущему звонку, отправив в ответ на информацию:

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

где,

  • redirect – id сценария редиректа (в формате 0-1 где 0 номер голосового меню 1 номер сценария) или внутренний номер АТС, "blacklist" - в этом случае звонок будет отклонен с сигналом занято;
  • caller_name – можно дать имя входящему номеру.

Максимальное время ответа с информацией о редиректе и имени номера - до 2 секунд.

Пример скрипта можете посмотреть на нашем репозитории на GitHub.