События внутреннего номера (/extension/.../event/)

_{Протестировать методы API можно на странице}_{интерактивного обозревателя API}_{и без написания кода}
_{Некоторые ресурсы, описанные на странице, по умолчанию могут быть не доступны из-за типа приложения (см.}_{Создание и авторизация приложений}₎

С помощью данного ресурса можно оповещать сторонние приложения о событиях на внутреннем номере. Количество отслеживаемых событий лимитировано, лимит может быть получен через ресурс “Лимиты (/limit/)”.

Описание структур данных

Событие (Event)

Имя	Тип	Обяза-тельный	Значение по умолчанию	Описание

Имя

Тип

Обяза-тельный

Значение по умолчанию

Описание

url

string

да

URL. на который отправляется запрос при наступлении события. Например: 'https://myshost.org/calls'

event_type

string

да

Событие на внутреннем номере, при наступлении которого отправляется запрос. Возможны варианты:

dial-in – входящий вызов;
dial-out – исходящий вызов;
hangup – окончание соединения;
answer – ответ;
message-in – входящее сообщение;
message-out – исходящее сообщение

method

string

да

Метод запроса:

GET
POST

Данные события (EventData)

В случае, когда методом запроса является GET, данные будут содержаться в заголовке запроса, если же методом запроса является POST, данные будут содержаться в теле запроса. В обоих случаях данные находятся в формате application/x-www-form-urlencoded.

Имя	Тип	Описание

Имя	Тип	Описание
EventType	string	Тип события. Может принимать значения dial-in, dial-out, hangup, answer, message-in или message-out в зависимости от типа события
CallID	string	Уникальный идентификатор вызова. Не меняется при переадресациях. Можно использовать для идентификации принадлежности различных событий одному вызову
CallerIDNum	string	Номер вызывающего абонента
CallerIDName	string	Имя вызывающего абонента (если есть)
CalledDID	string	Публичный номер вызываемого абонента (если есть)
CalledExtension	string	Имя вызываемого внутреннего номера (в виде xxx*yyy@domain)
CalledExtensionID	int	Идентификатор внутреннего номера CalledExtension. Удобен для последующих вызовов API, ожидающих идентификатор
CallStatus	string	Статус вызова. Для event_type dial-in и dial-out: CALLING Для event_type answer: ANSWER Для event_type hangup: ANSWER — вызов был отвечен; BUSY — вызов получил сигнал "занято"; NOANSWER — звонок не отвечен (истек таймер ожидания на сервере); CANCEL — вызывающий абонент отменил вызов до истечения таймера ожидания на сервере; CONGESTION — произошла ошибка во время вызова; CHANUNAVAIL — у вызываемого абонента отсутствует регистрация Для event_type message-in и message-out данные событий доступны на странице “Сообщения (/message/) и чаты (/chat/)”.
CallFlow	string	Направление вызова: IN — входящий; OUT — исходящий
CallerExtension	string	Внутренний номер, с которого произведен вызов (в виде xxx*yyy@domain)
CallerExtensionID	int	Идентификатор внутреннего номера CallerExtension. Удобен для последующих вызовов API, ожидающих идентификатор
CalledNumber	string	Вызываемый номер
RecID	string	Если на внутреннем номере включена запись разговоров, то тут содержится ее идентификатор. Эквивалентно record_uuid в REST API. По нему можно получить файл записи. Имеет смысл только в событии hangup
CallAPIID	string	Уникальный идентификатор вызова для управления им (например: обрыв, перевод, парковка)
Diversion	string	Номер из одноименного поля протокола SIP при поступлении звонка на АТС (rfc5806). Опционально (присутствуют только при наличии в заголовках SIP). Обычно показывает номер, с которого была сделана переадресация до прихода вызова в АТС
EventTime	int	Время генерации события: микросекунды c 1 января 1970 года
Duration	int	Для события hangup содержит время разговора в микросекундах
Transfered	string	При наличии в событиях CallFlow=out позволяет отличать вызовы, инициированные внутренним номером, от вызовов, переадресованных с внутреннего номера: yes — исходящий вызов произошел в результате переадресации Поле может отсутствовать
Bridged	string	Присутствует в событиях очередей (CallFlow='in') и голосовых меню (IVR): yes — вызов был отвечен после попадания в очередь/IVR; no — вызов не был отвечен после попадания в очередь/IVR
CallBackID	string	Присутствует при инициации вызова. Может быть полезен для определения принадлежности множества событий к одной инициации вызова
SubCallID	string	В отличии от параметра CallID, одинакового для всего вызова, позволяет выделить в звонке составную часть. Например, если в пределах одного вызова звонок приходил на один внутренний номер несколько раз (например, несколько раз по кругу, как агент очереди), то этот параметр будет отличаться. Полезен для группировки dial-in, dial-out, answer, hangup составной части вызова
ClientApiID	string	Необязательный параметр. Включает содержимое SIP заголовка Client-Api-Id при формировании вызова на стороне клиента. Удобно использовать для соотношения событий со звонками, инициированными оборудованием клиента. Длина SIP заголовка не должна превышать 100 символов. Например: "Client-Api-Id: 1234567Az"
RemoteNumber	string	Необязательный параметр. Присутствует при входящих вызовах, если CallerIDNum не совпадает с номером, с которым устанавливается соединение (например, при трансфере исходящего вызова с одного внутреннего номера на другой)
ANI	string	Необязательный параметр. Для исходящих вызовов (CallFlow=out) на номера вне АТС (например, мобильные), позволяет определить, какой номер был установлен для идентификации

Особенности генерации

Голосовое меню (IVR): при поступлении вызова генерируется событие dial-in, при отбое – hangup (таким образом, события dial-out и answer отсутствуют).

Очередь работает с двумя потоками:

Поток	Описание

Поток	Описание
in	При поступлении звонка в очередь – dial-in, при завершении соединения – hangup (событие answer отсутствует)
out	При обзвоне каждого из агентов очереди – dial-out, если вызов был отвечен – answer, при завершении соединения – hangup

Если вызов уходит на переадресацию по правилам входящего вызова на номер вне АТС (не важно, с какого типа внутреннего номера), то с этого внутреннего номера генерируется событие dial-out на соответствующий номер с параметром Transfered: "yes".

Допустим, используется следующая инициация вызова (callback):

POST /extension/@200/callback/
{
  "dst_num": "+79817654321",
  "src_num": [
    "200"
  ]
}

Если при этом внутренний номер “200” является владельцем звонка и осуществляет вызов на самого себя, то для оптимизации не будет событий вызова самого внутреннего номера. Например, соединение внутреннего номера "200" с номером "+79817654321" от имени внутреннего номера "200" инициирует "dial-out" с "200" на "+79817654321" (не будет "dial-in" с "200" на "200" и "dial-out" с "200" на "200").

События message-in и message-out доступны только для внутренних номеров типа “phone”

Пример

Для внутреннего номера 000*099 с идентификатором 175 и включенной записью разговоров добавим события dial-out', 'answer', 'hangup'. Во все URL добавлены параметры "?myid=175", чтобы на стороне https://somehost.com/ было понятно, кому принадлежит событие в случае событий с разных внутренних номеров.

Ответ системы:

{
  "url": "https://somehost.com/fordel/show.php?myid=175",
  "method": "GET",
  "event_type": "dial-out",
  "id": 72
}

Ответ системы:

{
  "url": "https://somehost.com/fordel/show.php?myid=175",
  "method": "GET",
  "event_type": "answer",
  "id": 73
}

Ответ системы:

{
  "url": "https://somehost.com/fordel/show.php?myid=175",
  "method": "GET",
  "event_type": "hangup",
  "id": 74
}

Если на стороне somehost.com скрипт show.php имеет вид:

<?php
error_log("------");
foreach ($_GET as $key => $value){
    error_log("$key => $value");
}
?>

то после звонка с внутреннего номера 000*099 на номер 00010005 в файле логов web-сервера можно будет увидеть записи вида:

[Thu Jul 06 17:03:59 2017]  ------
[Thu Jul 06 17:03:59 2017]  myid => 175
[Thu Jul 06 17:03:59 2017]  SubCallID => 175-31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:03:59 2017]  EventTime => 1499349840250190
[Thu Jul 06 17:03:59 2017]  CalledNumber => 00010005
[Thu Jul 06 17:03:59 2017]  EventType => dial-out
[Thu Jul 06 17:03:59 2017]  CallerIDNum => 000*099
[Thu Jul 06 17:03:59 2017]  CallerExtensionID => 175
[Thu Jul 06 17:03:59 2017]  CallerExtension => 000*099@sip.domain
[Thu Jul 06 17:03:59 2017]  CallFlow => out
[Thu Jul 06 17:03:59 2017]  CallAPIID => 3584705177-31845fca-8562-4b7a-94cf-7b4036fd6d52
[Thu Jul 06 17:03:59 2017]  CallerIDName => Iggy Pop
[Thu Jul 06 17:03:59 2017]  CallStatus => CALLING
[Thu Jul 06 17:03:59 2017]  CallID => 31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:04:01 2017]  ------
[Thu Jul 06 17:04:01 2017]  myid => 175
[Thu Jul 06 17:04:01 2017]  SubCallID => 175-31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:04:01 2017]  EventTime => 1499349842091175
[Thu Jul 06 17:04:01 2017]  CalledNumber => 00010005
[Thu Jul 06 17:04:01 2017]  EventType => answer
[Thu Jul 06 17:04:01 2017]  CallerIDNum => 000*099
[Thu Jul 06 17:04:01 2017]  CallerExtensionID => 175
[Thu Jul 06 17:04:01 2017]  CallerExtension => 000*099@sip.domain
[Thu Jul 06 17:04:01 2017]  CallFlow => out
[Thu Jul 06 17:04:01 2017]  CallAPIID => 3584705177-31845fca-8562-4b7a-94cf-7b4036fd6d52
[Thu Jul 06 17:04:01 2017]  CallerIDName => Iggy Pop
[Thu Jul 06 17:04:01 2017]  CallStatus => ANSWER
[Thu Jul 06 17:04:01 2017]  CallID => 31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:04:05 2017]  ------
[Thu Jul 06 17:04:05 2017]  myid => 175
[Thu Jul 06 17:04:05 2017]  SubCallID => 175-31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:04:05 2017]  EventTime => 1499349846331075
[Thu Jul 06 17:04:05 2017]  CalledNumber => 00010005
[Thu Jul 06 17:04:05 2017]  EventType => hangup
[Thu Jul 06 17:04:05 2017]  CallerIDNum => 000*099
[Thu Jul 06 17:04:05 2017]  CallerExtensionID => 175
[Thu Jul 06 17:04:05 2017]  CallerExtension => 000*099@sip.domain
[Thu Jul 06 17:04:05 2017]  CallFlow => out
[Thu Jul 06 17:04:05 2017]  RecID => 175-31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:04:05 2017]  CallAPIID => 3584705177-31845fca-8562-4b7a-94cf-7b4036fd6d52
[Thu Jul 06 17:04:05 2017]  CallerIDName => Iggy Pop
[Thu Jul 06 17:04:05 2017]  Duration => 4239900
[Thu Jul 06 17:04:05 2017]  CallStatus => ANSWER
[Thu Jul 06 17:04:05 2017]  CallID => 31845fca85624b7a94cf7b4036fd6d52

Ресурсы раздела “Внутренний номер”

POST /extension/{extension_id}/event/

Добавить событие внутреннего номера

Параметры URL

Имя	Тип

Имя	Тип
extension_id	string

Параметры JSON

Имя	Тип	Обязательный

Имя	Тип	Обязательный
url	string	да
event_type	string	да
method	string	да

Поля ответа

Имя	Тип

Имя	Тип
url	string
method	string
event_type	string
id	long

GET /extension/{extension_id}/event/

Получить список событий внутреннего номера

Параметры URL

Имя	Тип

Имя	Тип
extension_id	string

Поля ответа

Имя	Тип

Имя	Тип
url	string
method	string
event_type	string
id	long

DELETE /extension/{extension_id}/event/

Удалить все события внутреннего номера

Параметры URL

Имя	Тип

Имя	Тип
extension_id	string

PUT /extension/{extension_id}/event/{id}

Обновить событие внутреннего номера

Параметры URL

Имя	Тип

Имя	Тип
extension_id	string
id	integer

Параметры JSON

Имя	Тип	Обязательный

Имя	Тип	Обязательный
url	string	нет
event_type	string	нет
method	string	нет

Поля ответа

Имя	Тип

Имя	Тип
url	string
method	string
event_type	string
id	long

GET /extension/{extension_id}/event/{id}

Получить событие внутреннего номера

Параметры URL

Имя	Тип

Имя	Тип
extension_id	string
id	integer

Поля ответа

Имя	Тип

Имя	Тип
url	string
method	string
event_type	string
id	long

DELETE /extension/{extension_id}/event/{id}

Удалить событие внутреннего номера

Параметры URL

Имя	Тип

Имя	Тип
extension_id	string
id	integer