События добавочного (/extension/.../event/)
Мы обновили документацию, актуальная версия страницы доступна по ссылке: События внутреннего номера (/extension/.../event/)
С помощью ресурса можно оповещать сторонние приложения о событиях на добавочном. Количество отслеживаемых событий лимитировано, лимит может быть получено через ресурс лимитов.
Описание структур данных
Событие (Event)
Имя | Тип | Обязательный | Значение По Умолчанию | Описание |
---|---|---|---|---|
|
|
| Куда отправляется запрос при наступлении события. Например, 'https://myshost.org/calls' | |
|
|
| Событие на добавочном, при наступлении которого отправлять запрос. Возможны варианты: | |
|
|
| Метод запроса:
|
Особенности генерации
Голосове меню (IVR): при поступлении вызова генерируется 'dial-in', при отбое 'hangup' (таким образом, 'dial-out' и 'answer' остуствуют).
Очердь работает с двумя потоками:
Поток | Описание |
---|---|
in | При поступлении звонка в очередь: 'dial-in' при завершении соединения 'hangup' ( 'answer' остуствует). |
out | При обзвоне каждого из агентов очереди: 'dial-out', 'answer' (если был), 'hangup' |
Если вызов уходит на переадресацию по правилам входящего вызова на номер вне АТС (не важно с какого типа добавочного), то генерируется 'dial-out' с этого добавочного на соответствующий номер (с параметром Transfered: "yes").
При использовании callback, если добавочный является владельцем звонка и осуществляет вызов на самого себя, то для оптимизации не будет событий вызова самого добавочного. Например, соединение добавочного "200" с номером "+79817654321" от имени добавочного "200", инициирует "dial-out" с "200" на "+79817654321" (не будет "dial-in" с "200" на "200" и "dial-out" с "200" на "200")
POST /extension/@200/callback/ { "dst_num": "+79817654321", "src_num": [ "200" ] }
Данные события (EventData)
В случае, когда методом запроса является GET, данные будут содержаться в заголовке запроса, если же методом запроса является POST, данные будут содержаться в теле запроса. В обоих случаях данные находятся в формате application/x-www-form-urlencoded.
Имя | Тип | Описание |
---|---|---|
EventType |
| Тип события. Может принимать значния dial-in, dial-out, hangup или answer в зависимости от типа события. |
CallID |
| Уникальный идентификатор вызова. Не меняется при переадресациях. Можно использовать для идентификации принадлежности различных событий одному вызову. |
CallerIDNum |
| Номер вызывающего абонента |
CallerIDName |
| Имя вызывающего абонента (если есть). |
CalledDID | string | Публичный номер вызываемого абонента (если есть) |
CalledExtension | string | Имя вызываемого добавочного (в виде xxx*yyy@domain) |
CalledExtensionID | int | Идентификатор добавочного CalledExtension. Удобен для последующих вызовов API, ожидающих идентификатор |
CallStatus | string | Статус вызова. Для event_type 'dial-in' и 'dial-out' :
Для event_type 'answer' :
Для event_type 'hangup':
|
CallFlow | string | Направление вызова:
|
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 позволяет отличать вызовы, инициированные добавочным, от вызовов, переадресованных с добавочного:
|
Bridged | string | Присутствует в событиях очередей (CallFlow='in') и голосовых меню (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) на номера вне АТС (например, мобильные), позволяет определить, какой номер был установлен для идентификации. |
Пример использования
Для добавочного 000*099 с идентификатором 175 и включенной записью разговоров, добавим события dial-out', 'answer', 'hangup'. Во все URL добавлены параметры "?myid=175", чтобы на стороне https://somehost.com/ было понятно кому принадлежит событие в случае событий с разных добавочных.
метод | ресурс | данные | ответ |
---|---|---|---|
POST | /extension/175/event/ | { | { |
метод | ресурс | данные | ответ |
---|---|---|---|
POST | /extension/175/event/ | { | { |
метод | ресурс | данные | ответ |
---|---|---|---|
POST | /extension/175/event/ | { | { |
Если на стороне 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/
Добавить extension event
Параметры URL
Имя | Тип |
---|---|
|
|
Параметры JSON
Имя | Тип | Обязательный |
---|---|---|
|
|
|
|
|
|
|
|
|
Поля ответа
Имя | Тип |
---|---|
|
|
|
|
|
|
|
|
GET /extension/{extension_id}/event/
Получить extension event list
Параметры URL
Имя | Тип |
---|---|
|
|
Поля ответа
Имя | Тип |
---|---|
|
|
|
|
|
|
|
|
DELETE /extension/{extension_id}/event/
Удалить все extension events
Параметры URL
Имя | Тип |
---|---|
|
|
PUT /extension/{extension_id}/event/{id
}
Обновить extension event
Параметры URL
Имя | Тип |
---|---|
|
|
|
|
Параметры JSON
Имя | Тип | Обязательный |
---|---|---|
|
|
|
|
|
|
|
|
|
Поля ответа
Имя | Тип |
---|---|
|
|
|
|
|
|
|
|
GET /extension/{extension_id}/event/{id
}
Получить extension event
Параметры URL
Имя | Тип |
---|---|
|
|
|
|
Поля ответа
Имя | Тип |
---|---|
|
|
|
|
|
|
|
|
DELETE /extension/{extension_id}/event/{id
}
Удалить extension event
Параметры URL
Имя | Тип |
---|---|
|
|
|
|
Теги по теме