С помощью данного ресурса можно оповещать сторонние приложения о событиях на внутреннем номере. Количество отслеживаемых событий лимитировано, лимит может быть получен через ресурс “Лимиты (/limit/)”.
Описание структур данных
Событие (Event)
Имя
Тип
Обяза-тельный
Значение по умолчанию
Описание
Имя
Тип
Обяза-тельный
Значение по умолчанию
Описание
url
string
да
URL. на который отправляется запрос при наступлении события. Например: 'https://myshost.org/calls'
event_type
string
да
Событие на внутреннем номере, при наступлении которого отправляется запрос. Возможны варианты:
В случае, когда методом запроса является 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 — у вызываемого абонента отсутствует регистрация
Внутренний номер, с которого произведен вызов (в виде 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".
Если при этом внутренний номер “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/ было понятно, кому принадлежит событие в случае событий с разных внутренних номеров.