Интерфейс API от Zadarma

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

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

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

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

Версия АПИ: v1

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

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

Инструкция по интеграции собственной CRM и телефонии Zadarma

Авторизация

Каждый запрос, который нуждается в авторизации, сопровождается дополнительным заголовком, вида:
"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>

Доступные методы:

/v1/info/balance/
баланс пользователя.
/v1/info/price/
стоимость звонка с учетом текущего тарифа пользователя.
/v1/info/timezone/
часовой пояс пользователя.
/v1/tariff/
информация о текущем тарифе пользователя.
/v1/request/callback/
обратный звонок.
/v1/sip/
список SIP-номеров пользователя.
/v1/sip/<SIP>/status/
online-статус SIP-номера пользователя.
/v1/sip/callerid/
изменение CallerID.
/v1/sip/redirection/
отображение текущих переадресаций по SIP-номерам пользователя.
/v1/direct_numbers/
информация о прямых номерах пользователя.
/v1/sip/redirection/
включение/выключение переадресации по номеру SIP.
/v1/sip/redirection/
изменение параметров переадресации.
/v1/pbx/internal/
отображение внутренних номеров АТС.
/v1/pbx/internal/<PBXSIP>/status/
online-статус внутреннего номера АТС.
/v1/pbx/internal/recording/
включение записи разговоров на внутреннем номере АТС.
/v1/pbx/record/request/
запрос на файл записи разговора.
/v1/pbx/redirection/
изменение параметров переадресации на внутреннем номере АТС.
/v1/pbx/redirection/
получение параметров переадресации на внутреннем номере АТС.
/v1/sms/send/
отправка SMS.
/v1/statistics/
получение общей статистики.
/v1/statistics/pbx/
статистика по АТС.
/v1/statistics/callback_widget/
статистика по Виджету обратного звонка.
/v1/info/number_lookup/
актуализация контактов.

JSON
XML

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

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

Параметры:

number – номер телефона
caller_id (опционально) – CallerID, который будет использоваться при совершении звонка.

JSON
XML

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

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

JSON
XML

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

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

JSON
XML

{
    "status":"success",
    "info": {
        "tariff_id":5,
        "tariff_name":"Standart, special",
        "is_active":false,
        "cost":0,
        "currency":USD,
        "used_seconds":1643,
        "used_seconds_mobile":34,
        "used_seconds_fix":726,
        "tariff_id_for_next_period":5,
        "tariff_for_next_period":Standart, special
    }
}

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

где

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 – наименование тарифа пользователя на следующий период.

Параметры:

from – ваш номер телефона или SIP, или внутренний номер АТС, или номер сценария АТС, на который вызывается callback;
to – номер телефона или SIP, которому звонят;
sip (опционально) – номер SIP-пользователя или внутренний номер АТС (например 100), через который произойдет звонок. Будет использован CallerID этого номера, в статистике будет отображаться данный номер SIP/АТС, если для указанного номера включена запись звонков либо префиксы набора, они также будут задействованы; 
predicted (опционально) – если указан этот флаг, то запрос является предикативным (система изначально звонит на номер "to" и только если ему дозванивается, соединяет с вашим SIP либо телефонным номером);

JSON
XML

{
    "status":"success",
    "from": 442037691880,
    "to": 442037691881,
    "time": 1435573082
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <from>442037691880</from>
    <to>442037691881</to>
    <time>1435573082</time>
</answer>

JSON
XML

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

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

где

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

JSON
XML

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

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

Параметры:

id – SIP id, которому меняют CallerID;
number – номер, на который меняют в международном формате (из списка подтвержденных либо приобретенных номеров пользователя).

JSON
XML

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

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

Параметры:

id – (опциональный) выбор конкретного SIP id.

JSON
XML

{
    "status":"success",
    "info": [
        {
        "sip_id":"00001",
        "status":"on",
        "condition":"always",
        "destination":"phone",
        "destination_value":"442037691880",
        },
    ...
    ]
}

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

где

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

JSON
XML

{
    "status":"success",
    "info": [
        {
            "number":"442037691880",
            "status":"on",
            "country":"Great Britain",
            "description":"London",
            "number_name":null,
            "sip":00001,
            "sip_name":null,
            "start_date":"2015-01-01 18:14:44",
            "stop_date":"2016-02-11 18:14:40",
            "monthly_fee":2,
            "currency":USD,
            "channels":2,
            "autorenew":"true",
            "is_on_test":"false",
            "type":"common"
        },
    ...
    ]
}

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

В зависимости от типа номера набор полей может отличаться! Описание полей:

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)

Параметры:

id – SIP id;
status – выставляемый статус переадресации на выбранный SIP-номер.

JSON
XML

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

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

Параметры:

id – SIP id;
type – тип переадресации: phone – на телефон;
number – номер телефона.

JSON
XML

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

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

JSON
XML

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

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

где

pbx_id – id ATC пользователя;
numbers – список внутренних номеров.

JSON
XML

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

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

где

pbx_id – АТС-id;
number – внутренний номер АТС;
is_online – online-статус (true|false).

Параметры:

id – внутренний номер АТС;
status – статус: "on" - включить, "off" - отключить, "on_email" - включить только запись на почту, "off_email" - отключить только запись на почту, "on_store" - включить только запись в хранилище, "off_store" - отключить только запись в хранилище;
email – (опциональный) изменение электронного адреса, куда будут отправляться записи разговоров. Вы можете указать до 3х email адресов через запятую.

JSON
XML

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

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

Параметры:

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

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

JSON
XML

Пример ответа когда указан только call_id, ссылка только одна:

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

Пример ответа когда указан только pbx_call_id, ссылок может быть несколько:

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

Пример ответа когда указан только call_id, ссылка только одна:

<?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, ссылок может быть несколько:

<?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 – до которого времени ссылка будет работать.

Параметры:

Для включения и настройки переадресации:

pbx_number – внутренний номер АТС в полном формате, например 1234-100;
status – on;
type – тип переадресации voicemail или phone;
destination – телефон или электронная почта, в зависимости от предыдущего параметра;
condition – условие переадресации, возможные значения: always или noanswer;
set_caller_id – установка вашего CallerID при переадресации, возможные значения: on, off. Указывается только при type = phone;
voicemail_greeting – оповещение о переадресации, возможные значения: no, standart, own. Указывается только при type = voicemail;
greeting_file – файл с оповещением в формате mp3 или wav до 5 MB. Указывается только при type = voicemail и voicemail_greeting = own;

Для выключения переадресации:

pbx_number – внутренний номер АТС в полном формате, например 1234-100;
status – off;

JSON
XML

{
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
    }

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

Параметры:

pbx_number – внутренний номер АТС в полном формате, например 1234-100;

JSON

{
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
    }

Параметры:

number – номер телефона, куда отправлять SMS (можно перечислить несколько через запятую);
message – сообщение (стандартные ограничения по длине SMS, в случае превышения лимита – разбивается на несколько SMS);
caller_id – (опциональный) номер телефона, от кого будет отправлена SMS (можно отправлять только из списка подтвержденных номеров пользователя).

Обратите внимание: отправка SMS доступна только за пределы РФ.

JSON
XML

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

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

Параметры:

start - дата начала просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
end - дата окончания просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
sip (опционально) - фильтр по определенному SIP-номеру;
cost_only (опционально) - просмотр только потраченных средств за период;
type (опционально - только на общей статистики) - тип запроса: общий (не указывается в запросе), toll и ru495. (для статистики номеров 800 и бесплатных номеров 495);
skip (опционально - не учитывается при заданном параметре cost_only) - количество строк, которое необходимо пропустить в выборке, вывод начнется со строки skip + 1 (используется для пагинации совместно с параметром limit, по умолчанию равняется 0);
limit (опционально - не учитывается при заданном параметре cost_only) - ограничение на количество выводимых строк (используется для пагинации совместно с параметром skip, максимальное значение 1000, по умолчанию 1000).

Максимальный период получения статистики - месяц. В случае превышения лимита в запросе - период автоматически сокращается до 30 дней. Если не указана дата начала выборки, выбирается начало текущего месяца. Если не указана дата конца выборки – выборка ограничивается текущей датой и временем.
Максимальное количество выводимых строк для одного запроса - 1000. Для пагинации используйте параметры skip и limit.

JSON
XML

{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 13:45:23",
    "stats":[
        {
            "id":"155112249",
            "sip":"00001",
            "callstart":"2015-06-02 12:20:25",
            "from":442037691880,
            "to":442037691881,
            "description":"United Kingdom, London",
            "disposition":"busy",
            "billseconds":0,
            "cost":0.1950,
            "billcost":0.0000,
            "currency":"USD"
        },
        …
    ]
}

?type=cost_only:

{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 14:03:57",
    "stats":[
        {
            "cost":38.094,
            "currency":"USD",
            "seconds":9785
        }
    ]
}

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

?type=cost_only:

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2015-06-01 00:00:00</start>
    <end>2015-06-29 14:03:30</end>
    <stats>
    <value>
        <cost>38.094</cost>
        <currency>USD</currency>
        <seconds>9785</seconds>
    </value>
    </stats>
</answer>

где

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 – куда звонили.

Параметры:

start - дата начала просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
end - дата окончания просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
version - формат вывода статистики (2 - новый, 1 - старый);
skip (опционально) - количество строк, которое необходимо пропустить в выборке, вывод начнется со строки skip + 1 (используется для пагинации совместно с параметром limit, по умолчанию равняется 0);
limit (опционально) - ограничение на количество выводимых строк (используется для пагинации совместно с параметром skip, максимальное значение 1000, по умолчанию 1000);
call_type (опционально) - направление звонков ('in' для входящих, 'out' для исходящих). Если не указан, выводятся все звонки.

JSON
XML

{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-30 23:59:59",
    "version":2,
    "stats":[
        {
            "call_id":1439981389.2702773,
            "sip":200,
            "callstart":"2015-06-01 15:04:00",
            "clid":200,
            "destination":5,
            "disposition":"answered",
            "seconds":5,
            "is_recorded":true,
            "pbx_call_id":"in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d"
        },
        …
    ]
}

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

где

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 и т.д., отображается в статистике и уведомлениях);

Параметры:

start - дата начала просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
end - дата окончания просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
widget_id - (опционально) - идентификатор виджета, в случае отсутствия параметра берется статистика по всем виджетам;

JSON
XML

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

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

где

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').

Параметры:

numbers – список номеров для актуализации в международном формате.

Если numbers содержит 1 номер, результат будет возвращен сразу, если указан список номеров, результат будет отправлен по адресу, указанному на странице актуализации контактов, либо отправлен на email, если адрес не задан.

Обратите внимание: настройки данного метода проводятся на странице актуализации номеров в личном кабинете.

Пример ответа для 1 номера:


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

Пример ответа для нескольких номеров:


{
    "status":"success"
}

Пример результата, отправленного по адресу, указанному на странице актуализации:


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

Система уведомлений о звонках - webhook

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

Доступные методы:

NOTIFY_START
начало входящего звонка в АТС.
NOTIFY_INTERNAL
начало входящего звонка на внутренний номер АТС.
NOTIFY_ANSWER
ответ при звонке на внутренний или на внешний номер.
NOTIFY_END
конец входящего звонка на внутренний номер АТС.
NOTIFY_OUT_START
начало исходящего звонка с АТС.
NOTIFY_OUT_END
конец исходящего звонка с АТС.
NOTIFY_RECORD
запись звонка готова для скачивания.
NOTIFY_IVR
ответ абонента на заданное действие.

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

event – событие (NOTIFY_START)
call_start – время начала звонка;
pbx_call_id – id звонка;
caller_id – номер звонящего;
called_did – номер, на который позвонили.

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

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

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

Воспроизвести файл:

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

где,

ivr_play – значение из колонки ID в списке загруженных/начитанных файлов для нужного файла;
wait_dtmf – обязательный параметр, описан ниже.

Воспроизвести популярную фразу:

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

где,

ivr_saypopular – номер фразы из списка;

Воспроизвести цифры:

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

Воспроизвести число (в соответствии с правилами сложных числительных):

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

где,

language может принимать одно из значений: ru, en, es, pl;

Если были указаны ivr_saydigits или ivr_saynumber, в следующем событии NOTIFY_IVR будет добавлен параметр:

"ivr_saydigits": "COMPLETE" или "ivr_saynumber": "COMPLETE"

В каждом из указанных запросов выше может присутствовать запрос ввода цифр от абонента:

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

где,

timeout - время ожидания ввода цифр в секундах;
attempts - количество попыток набора цифры от абонента;
maxdigits - максимальное количество цифр, ввода которых дожидаться;
name - имя, которое будет возвращено в ответе;
default - действие, если не было набрано ни одной цифры. Возможные значения:
- id сценария редиректа (в формате 0-1, где 0 - номер голосового меню, 1 - номер сценария);
- меню АТС в формате 0-main, где 0 - это id меню;
- внутренний номер АТС (трехзначный номер);
- hangup - закончить звонок.

В следующем событии NOTIFY_IVR будет дополнительно указан параметр:

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

где,

name - имя, указанное в предыдущем ответе;
digits - цифры, введенные абонентом;
default_behaviour - указано, если абонент ничего не нажал и сработало поведение по умолчанию;

Перевести звонок:

{
    "redirect": ID,
    "return_timeout": TIMEOUT (необязательное)
}

где,

redirect - id сценария редиректа (в формате 0-1, где 0 - номер голосового меню, 1 - номер сценария); или в формате 1, где 1 - номер сценария(номер голосового меню в этом случае 0); или меню АТС в формате 0-main, где 0 - это id меню; или внутренний номер АТС (трехзначный номер); или "blacklist" - в этом случае звонок будет отклонен с сигналом занято;
return_timeout - Значение в секундах. Возможные значения:
- 0, звонок не вернется на меню;
- >= 3 - продолжительность звонка внутреннего номер, прежде чем звонок вернется на меню
default_behaviour - указано, если абонент ничего не нажал и сработало поведение по умолчанию;

Завершить звонок:

{
    "hangup": 1
}

В каждом из ответов можно дополнительно указать:

Задать имя для имя входящего номера:

{
	"caller_name": NAME
}

где,

caller_name - имя номера.

Списки популярных фраз:

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

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

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

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

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

event – событие (NOTIFY_ANSWER)
caller_id – номер звонящего;
destination – номер, на который позвонили;
call_start – время начала звонка;
pbx_call_id – id звонка;
internal – (опциональный) внутренний номер.

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

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

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

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

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

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

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

event – событие (NOTIFY_OUT_START)
call_start – время начала звонка;
pbx_call_id – id звонка;
destination – номер, на который позвонили;
caller_id – номер, настроенный на внутреннем номере АТС или установленный в правилах набора по направлениям. Если номер не установлен, то передается 0;
internal – (опциональный) внутренний номер.

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

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

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

event – событие (NOTIFY_OUT_END)
call_start – время начала звонка;
pbx_call_id – id звонка;
caller_id – номер, настроенный на внутреннем номере АТС или установленный в правилах набора по направлениям. Если номер не установлен, то передается 0;
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 секунд после уведомления т.к. для сохранения файла записи нужно время).

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

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

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

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

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

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

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

event – событие (NOTIFY_IVR)
call_start – время начала звонка;
pbx_call_id – id звонка;
caller_id – номер звонящего;
called_did – номер, на который позвонили.

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

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

Возможные отправляемые ответы аналогичны ответам запросов NOTIFY_START

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

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

Пример на PHP:

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

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

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

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

Другие уведомления:

Параметр "result" в этих уведомлениях задан в JSON формате. Вы можете получить его в XML формате, указав в ссылке параметр format=xml.

NUMBER_LOOKUP
отчет о проверке номеров.
CALL_TRACKING
информацию о звонках на номера, подключенные к коллтрекингу.
SMS
информацию о входящих SMS.

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

event – событие (NUMBER_LOOKUP)
success – флаг успешности проверки;
description – текстовое описание статуса завершения проверки;
result – данные отчета;
- number – проверяемый номер;
- mcc – мобильный код страны;
- mnc – код мобильной сети;
- ported – признак переноса к другому оператору;
- roaming – признак нахождения в роуминге;
- error – статус ошибки;
- errorDescription – текстовое описание ошибки;
- mccName – название страны;
- mncName – название оператора;

Составление проверочной подписи:

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

Отправляется раз в 15 минут, при наличии новых звонков.

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

event – событие (CALL_TRACKING)
result - массив
- tracker - ID трекера (можно узнать на странице установки кода);
- start - время начала звонка;
- duration - длительность звонка в секундах;
- caller_id - номер звонящего;
- caller_did - номер, на который позвонили;
- country - (опционально) страна, из которой был совершен звонок;
- ga_id - (опционально, если в настройках указан Id Google Analytics) id посетителя в Google Analytics;
- metrika_id - (опционально, еcли в настройках указан Id Yandex.Metrika) id посетителя в Yandex.Metrika;

Составление проверочной подписи:

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

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

event – событие (SMS)
result – массив;
caller_id – номер отправителя;
caller_did – номер получателя;
text – текст сообщения.

Составление проверочной подписи:

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