Интерфейс API

Введение

API 2.0

Для клиентов, перешедших на платформу Novofon 2.0, доступны обновленные методы API
Ознакомиться с ними можно по следующим ссылкам:

DATA API
https://novofon.github.io/data_api/
CALL API
https://novofon.github.io/call_api/

Клиенты API

Интерфейс API абсолютно бесплатен и доступен на всех учетных записях Novofon
Для доступа к API можно использовать готовый клиент на языке программирования PHP:

https://github.com/novofon/user-api-v1

Авторизация

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

Ключи для авторизации необходимо получить в личном кабинете администратора в разделе Пользователи АТС - редактирование пользователя - Администратор - API

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

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

Заголовок Content-Type для POST запросов должен быть равным application/x-www-form-urlencoded либо multipart/form-data.

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

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;

Ограничения

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

X-Novofon-Method: /v1/ X-RateLimit-Reset: 1434371160 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99
где,

X-Novofon-Method - текущий вызываемый метод;
X-RateLimit-Reset - количество оставшихся запросов, с учетом лимита на метод и на пользователя;
X-RateLimit-Limit - цифра общего лимита обращений в минуту;
X-RateLimit-Remaining - время сброса лимита.

Общие ограничения - 100 запросов в минуту.
В случае блокировки, метод отдает ответ с 429 заголовком "You exceeded the rate limit".

Ответ состоит из обязательного ключа "status" (success или error). Далее, в зависимости от метода, отдаются свои ключи с запрашиваемой информацией.
В случае ошибки, отдается дополнительный ключ "message" с описанием ошибки.

Также, все ответы сопровождаются соответствующими HTTP-заголовками.

Внимание: если нужна постоянно актуальная статистика АТС, не нужно запрашивать каждую минуту метод statistics/pbx/. Включите уведомления webhooks и получайте информацию о каждом звонке в момент его начала и окончания.

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

Базовые методы

GET/v1/info/balance/

баланс пользователя

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

GET/v1/info/timezone/

часовой пояс пользователя

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

GET/v1/request/callback/

обратный звонок

Параметры:

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

{
  "status":"success",
  "from":74951270777,
  "to":74951270778,
  "time":1435573082
}

GET/v1/request/checknumber/

подтверждение номера

Параметры:

caller_id – номер, отображаемый при звонке, доступны только номера, подключенные в системе;
to – номер телефона или SIP, которому звонят;
code (опционально) – код, который будет воспроизводиться. Только цифры и длина не более 20 символов;
predicted (опционально) – язык начитки. При отсутствии - берется из ЛК клиента, проверяется на наличие в языках системы.

{
  "status":"success",
  "from":74951270777,
  "to":74951270778,
  "lang":"ru",
  "time":1612779278
}

GET/v1/info/lists/currencies/

Список валют

{
  "status": "success",
  "currencies": [
    "RUB"
  ]
}

GET/v1/info/lists/languages/

Список доступных языков в ЛК

{
  "status": "success",
  "languages": [
    "ru"
  ]
}

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 ссылок в ответе на запрос может быть несколько.

Где:

link – ссылка на файл разговора;
lifetime_till – до которого времени ссылка будет работать.

Пример 1:
{
  "status":"success",
  "link": "https://media.novofon.ru/.mp3",
  "lifetime_till": "2016-01-01 23:56:22"
}

Пример 2:
{
  "status":"success",
  "links":[
    "https://api.novofon.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
    "https://api.novofon.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3"
  ],
  "lifetime_till": "2016-01-01 23:56:22"
}

SIP

GET/v1/sip/

список SIP-номеров пользователя

Где:

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

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

GET/v1/sip/<SIP>/status/

online-статус SIP-номера пользователя

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

Статистика

GET/v1/statistics/

получение общей статистики

Параметры:

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

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

Где:

start – дата начала отображения статистики;
end – дата окончания отображения статистики;
id – id звонка;
sip – SIP-номер;
callstart – время начала звонка;
description – описание направления звонка;
disposition – состояние звонка:
- answered – разговор,
- answered – разговор,
- busy – занято,
- cancel - отменен,
- no answer - без ответа,
- call failed - не удался,
- no money - нет средств, превышен лимит,
- unallocated number - номер не существует,
- no limit - превышен лимит,
- no day limit - превышен дневной лимит,
- line limit - превышен лимит линий,
- no money, no limit - превышен лимит;
billseconds – количество секунд звонка;
cost – стоимость минуты звонка по данному направлению;
billcost – стоимость оплаченных минут;
currency – валюта стоимости;
from – с какого номера звонили;
to – куда звонили.

Пример 1:
{
    "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":74951270777,
            "to":74951270778,
            "description":"Russia, Moscow",
            "disposition":"busy",
            "billseconds":0,
            "cost":0.1950,
            "billcost":0.0000,
            "currency":"RUB"
        },
    ]
}

Пример 2:
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 14:03:57",
    "stats":[
        {
            "cost":38.094,
            "currency":"RUB",
            "seconds":9785
        }
    ]
}

GET/v1/statistics/incoming-calls/

получение общей статистики входящих вызовов

Параметры:

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

Где:

start – дата начала отображения статистики;
end – дата окончания отображения статистики;
id – id звонка;
sip – SIP-номер;
callstart – время начала звонка;
from – с какого номера звонили;
to – куда звонили;
billseconds – количество секунд звонка;
description – описание направления звонка;
disposition – состояние звонка:
- answered – разговор,
- answered – разговор,
- busy – занято,
- cancel - отменен,
- no answer - без ответа,
- call failed - не удался,
- no money - нет средств, превышен лимит,
- unallocated number - номер не существует,
- no limit - превышен лимит,
- no day limit - превышен дневной лимит,
- line limit - превышен лимит линий,
- no money, no limit - превышен лимит;

{
  "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":74951270777,
      "to":74951270778,
      "billseconds":0,
      "disposition":"busy",
      "description":"United Kingdom, London"
    }
  ]
}

GET/v1/statistics/pbx/

статистика по АТС

Параметры:

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' для исходящих). Если не указан, выводятся все звонки.

Где:

start – дата начала отображения статистики;
end – дата окончания отображения статистики;
version - формат вывода статистики (2 - новый, 1 - старый);
call_id – уникальный id звонка, этот id уникален для каждой записи в статистике;
sip – SIP-номер;
callstart – время начала звонка;
clid – CallerID;
destination – куда звонили;
disposition – состояние звонка:
- answered – разговор,
- answered – разговор,
- busy – занято,
- cancel - отменен,
- no answer - без ответа,
- call 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 и т.д., отображается в статистике и уведомлениях);

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

GET/v1/statistics/callback_widget/

статистика по Виджету обратного звонка

Параметры:

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

Где:

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

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

АТС

GET/v1/pbx/internal/

отображение внутренних номеров АТС

Где:

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

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

GET/v1/pbx/internal/<PBXSIP>/status/

online-статус внутреннего номера АТС

Где:

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

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

Виртуальные номера

GET/v1/direct_numbers/countries/

список стран в которых можно заказать номер

Параметры:

language (опциональный) - если не задано выдаст на языке ЛК

{
  "status": "success",
  "info": [
    {
      "countryCode": "7",
      "countryCodeIso": "RU",
      "name": "Russia"
    }
  ]
}

GET/v1/direct_numbers/

информация о прямых номерах пользователя

Где:

number – купленный виртуальный номер пользователя;
status – статус номера;
- on – номер включен;
- parking – номер отключен (не было оплаты), но сохраняется на аккаунте 7 дней и может быть восстановлен после пополнения счета;
- checking – номер заказан, оплачен, все необходимые документы загружены, ожидает активации;
- checking_upload – номер заказан, оплачен, ожидается загрузка необходимых документов;
- reserved_on – номер зарезервирован до оплаты;
- reserved_checking – номер зарезервирован до оплаты, все необходимые документы загружены;
- reserved_checking_upload – номер зарезервирован до оплаты, ожидается загрузка документов;
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 (виртуальный номер), order (заказанный, но не подключенный номер)

{
  "status":"success",
  "info": [
    {
      "number":"74951270777",
      "status":"on",
      "country":"Russia",
      "description":"Moscow",
      "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":"RUB",
      "channels":2,
      "autorenew":"true",
      "is_on_test":"false",
      "type":"common"
    }
  ]
}

GET/v1/direct_numbers/number/

информация о купленном номере

Параметры:

type - может иметь одно из 2-х значений:
- 'revenue' - Бесплатный московский номер 495;
- 'common' - Обычный номер, все остальные;
number - номер.

{
  "status": "success",
  "info": {
    "number": "74951270777",
    "status": "on",
    "country": "Russia",
    "description": "Moscow",
    "number_name": "TT",
    "sip": "00004",
    "sip_name": "SIP",
    "start_date": "2016-06-08 14:32:17",
    "stop_date": "2016-06-29 10:52:18",
    "monthly_fee": 2,
    "currency": "RUB",
    "channels": "2",
    "autorenew": "true",
    "receive_sms": null,
    "is_on_test": "false"
  }
}

Webhooks

NOTIFY_START

начало входящего звонка в АТС

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

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 можно «на лету» изменять сценарий работы по текущему звонку. Для этого отправьте в ответ на вебхук один из следующих вариантов:

Перевести звонок (Пример 1)
- redirect - id сценария редиректа (в формате 0-1, где 0 - номер голосового меню, 1 - номер сценария); или в формате 1, где 1 - номер сценария(номер голосового меню в этом случае 0); или меню АТС в формате 0-main, где 0 - это id меню; или внутренний номер АТС (трехзначный номер); или "blacklist" - в этом случае звонок будет отклонен с сигналом занято;
- return_timeout - Значение в секундах. Возможные значения:
  - 0 - звонок не вернется на меню;
  - >= 3 - продолжительность звонка внутреннего номер, прежде чем звонок вернется на меню;
- rewrite_forward_number - переадресация на номер телефона. Необязательный параметр, доступен для использования только совместно с параметром redirect. Необходим для замены "на лету" номера телефона переадресации, который указан в настройках внутреннего номера АТС.
Завершить звонок (Пример 2)
Задать имя входящего номера (Пример 3)
- caller_name - имя номера.
Ожидание DTMF (Пример 4)
- timeout - время ожидания ввода цифр в секундах;
- attempts - количество попыток набора цифры от абонента;
- maxdigits - максимальное количество цифр, ввода которых дожидаться;
- name - имя, которое будет возвращено в ответе;
- default - действие, если не было набрано ни одной цифры. Возможные значения:
  - id сценария редиректа (в формате 0-1, где 0 - номер голосового меню, 1 - номер сценария);
  - меню АТС в формате 0-main, где 0 - это id меню;
  - внутренний номер АТС (трехзначный номер);
  - hangup - закончить звонок.
Воспроизвести файл (Пример 5)
- ivr_play – значение из колонки ID в списке загруженных/начитанных файлов для нужного файла.
Воспроизвести популярную фразу (Пример 6)
- ivr_saypopular – номер фразы из списка;
Воспроизвести цифры (Пример 7)
Воспроизвести число (в соответствии с правилами сложных числительных) (Пример 8)

Пример 1:
{
    "redirect": "0-1",
    "return_timeout": 30
}

Пример 2:
{
    "hangup": 1
}

Пример 3:
{
    "caller_name": "Custom caller name"
}

Пример 4:
{
    "wait_dtmf": {
        "timeout": TIMEOUT,
        "attempts": ATTEMPTS,
        "maxdigits": MAXDIGITS,
        "name": NAME,
        "default": DEFAULT,
    }
}

Пример 5:
{
    "ivr_play": "ID"
}

Пример 6:
{
    "ivr_saypopular": 1,
    "language": "ru"
}

Пример 7:
{
    "ivr_saydigits": "12",
    "language": "ru"
}

Пример 8:
{
    "ivr_saynumber": "123",
    "language": "ru"
}

NOTIFY_INTERNAL

начало входящего звонка на внутренний номер АТС

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

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

// Составление проверочной подписи, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

NOTIFY_ANSWER

ответ при звонке на внутренний или на внешний номер

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

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

// Составление проверочной подписи, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['destination'] . 
        $_POST['call_start'], API_SECRET));

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 - превышен лимит;
last_internal – внутренний номер, последний участник звонка (после трансфера или перехвата);
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));

NOTIFY_OUT_START

начало исходящего звонка с АТС

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

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

NOTIFY_OUT_END

конец исходящего звонка с АТС

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

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

NOTIFY_RECORD

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

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

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

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

CALL_TRACKING

информацию о звонках на номера, подключенные к коллтрекингу

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

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

// Составление проверочной подписи, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

SMS

информацию о входящих SMS

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

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

// Составление проверочной подписи, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

SPEECH_RECOGNITION

результат распознавания голоса

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

event – событие (SPEECH_RECOGNITION)
lang – язык;
call_id – уникальный id звонка, этот id указан в названии файла с записью разговора;
pbx_call_id – постоянный ID внешнего звонка в АТС;
voicemail – опционально, если запись является сообщением на голосовую почту;
result:
- words - массив:
  - result - список слов (массив):
    - s - время начала слова
    - e - время окончания слова
    - w - слово
    - channel - номер канала
- phrases - массив:
  - result - фраза
  - channel - номер канала

// Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));