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

Owned by Asia Khalitova (Unlicensed)
Last updated: Aug 26, 2023 by Ilya Titaev
5 min read

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

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

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

Событие (Event)

Имя

Тип

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

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

Описание

Имя

Тип

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

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

Описание

url

string

да

 

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

event_type

string

да



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

  • dial-in – входящий вызов;

  • dial-out – исходящий вызов;

  • hangup – окончание соединения;

  • answer – ответ;

  • message-in – входящее сообщение;

  • message-out – исходящее сообщение;

  • voicemail – получено сообщение голосовой почты;

method

string

да



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

  • GET

  • POST 

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

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

Имя

Тип

Описание

Имя

Тип

Описание

EventType

string

Тип события. Может принимать значения dial-in, dial-out, hangup, answer, voicemail, 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 и voicemail

CallAPIID

string

Уникальный идентификатор вызова для управления им (например: обрыв, перевод, парковка)

Diversion

string

Номер из одноименного поля протокола SIP при поступлении звонка на АТС (rfc5806). Опционально (присутствуют только при наличии в заголовках SIP). Обычно показывает номер, с которого была сделана переадресация до прихода вызова в АТС

EventTime

int

Время генерации события: микросекунды c 1 января 1970 года

Duration

int

Для события hangup содержит время разговора в микросекундах. Для события voicemail - длительность сообщения

Transfered

string

При наличии в событиях CallFlow=out позволяет отличать вызовы, инициированные внутренним номером, от вызовов, переадресованных с внутреннего номера:

  • yes — исходящий вызов произошел в результате переадресации

Поле может отсутствовать

Bridged

string

Присутствует в событиях очередей (CallFlow='in') и голосовых меню (IVR):

  • yes — вызов был отвечен после попадания в очередь/IVR;

  • no — вызов не был отвечен после попадания в очередь/IVR

BridgedDuration

int

Для события hangup содержит время реального соединения в микросекундах. Опционально. Актуально для схем, когда время Duration не совпадает со временем реального разговора абонентов: например, если при инициации вызова первым плечом (параметр src_num) выступает очередь

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) на номера вне АТС (например, мобильные), позволяет определить, какой номер был установлен для идентификации

Tag

string

Если при инициации вызова задана переменная tag, то она появится в событиях этого вызова. С ее помощью удобно отслеживать принадлежность события группе вызовов.

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

Голосовое меню (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 }

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

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

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

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

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