Вы работаете с обновленной платформой Novofon 2.0. Подробная инструкция по работе с новым интерфейсом по ссылке. На все вопросы отвечаем в нашем онлайн-чате и тикетах. Оставайтесь на связи!

Введение

API 2.0

Для клиентов, перешедших на платформу Novofon 2.0, доступны обновленные методы 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).

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

Где:

  • 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/

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

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

Параметры:

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

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

Где:

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