Мы обновили документацию, актуальная версия страницы доступна по ссылке: События внутреннего номера (/extension/.../event/)

С помощью ресурса можно оповещать сторонние приложения о событиях на добавочном. Количество отслеживаемых событий лимитировано, лимит может быть получено через ресурс лимитов.

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

Событие (Event)

Имя

Тип

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

Значение По Умолчанию

Описание

url

string

да

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

event_type

string

да

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

'dial-in' - входящий вызов
'dial-out' - исходящий вызов
'hangup' - окончание соединения
'answer' - ответ
'message-in' - входящее сообщение (описание параметров события тут)
'message-out' - исходящее сообщение (описание параметров события тут)

method

string

да

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

GET
POST

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

Голосове меню (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	`string`	Тип события. Может принимать значния dial-in, dial-out, hangup или answer в зависимости от типа события.
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 у вызываемого абонента отсутствует регистрация
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) на номера вне АТС (например, мобильные), позволяет определить, какой номер был установлен для идентификации.

Пример использования

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

метод	ресурс	данные	ответ
POST	/extension/175/event/	{ "url": "https://somehost.com/fordel/show.php?myid=175", "method": "GET", "event_type": "dial-out" }	{ "url": "https://somehost.com/fordel/show.php?myid=175", "method": "GET", "event_type": "dial-out", "id": 72 }

метод	ресурс	данные	ответ
POST	/extension/175/event/	{ "url": "https://somehost.com/fordel/show.php?myid=175", "method": "GET", "event_type": "answer" }	{ "url": "https://somehost.com/fordel/show.php?myid=175", "method": "GET", "event_type": "answer", "id": 73 }

метод	ресурс	данные	ответ
POST	/extension/175/event/	{ "url": "https://somehost.com/fordel/show.php?myid=175", "method": "GET", "event_type": "hangup" }	{ "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/`

Добавить extension event

Параметры URL

Имя	Тип
`extension_id`	`string`

Параметры JSON

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

Поля ответа

Имя	Тип
`url`	`string`
`method`	`string`
`event_type`	`string`
`id`	`integer`

`GET /extension/{extension_id}/event/`

Получить extension event list

Параметры URL

Имя	Тип
`extension_id`	`string`

Поля ответа

Имя	Тип
`url`	`string`
`method`	`string`
`event_type`	`string`
`id`	`integer`

`DELETE /extension/{extension_id}/event/`

Удалить все extension events

Параметры URL

Имя	Тип
`extension_id`	`string`

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

Обновить extension event

Параметры URL

Имя	Тип
`extension_id`	`string`
`id`	`integer`

Параметры JSON

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

Поля ответа

Имя	Тип
`url`	`string`
`method`	`string`
`event_type`	`string`
`id`	`integer`

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

Получить extension event

Параметры URL

Имя	Тип
`extension_id`	`string`
`id`	`integer`

Поля ответа

Имя	Тип
`url`	`string`
`method`	`string`
`event_type`	`string`
`id`	`integer`

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

Удалить extension event

Параметры URL

Имя	Тип
`extension_id`	`string`
`id`	`integer`

REST API Документация клиента

События добавочного (/extension/.../event/)

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

Событие (Event)

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

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

Пример использования

Ресурсы

Раздел "добавочный"

`POST /extension/{extension_id}/event/`

Параметры URL

Параметры JSON

Поля ответа

`GET /extension/{extension_id}/event/`

Параметры URL

Поля ответа

`DELETE /extension/{extension_id}/event/`

Параметры URL

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

Параметры URL

Параметры JSON

Поля ответа

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

Параметры URL

Поля ответа

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

Параметры URL

Теги по теме

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

Событие (Event)

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

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

Пример использования

Ресурсы

Раздел "добавочный"

POST /extension/{extension_id}/event/

Параметры URL

Параметры JSON

Поля ответа

GET /extension/{extension_id}/event/

Параметры URL

Поля ответа

DELETE /extension/{extension_id}/event/

Параметры URL

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

Параметры URL

Параметры JSON

Поля ответа

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

Параметры URL

Поля ответа

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

Параметры URL

Теги по теме

`POST /extension/{extension_id}/event/`

`GET /extension/{extension_id}/event/`

`DELETE /extension/{extension_id}/event/`

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

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

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