События на внутренних номерах

Owned by Asia Khalitova (Unlicensed)
Last updated: Oct 19, 2020
4 min read

Всем обычным телефонным внутренним номерам (type = phone) рекомендуется добавлять полный набор событий:

  • dial-in — входящий вызов на внутренний номер – отправитель события;

  • dial-out — исходящий вызов с внутреннего номера – отправителя события;

  • answer — снятие трубки на внутреннем номере – отправителе события (возможно, в какой-то интеграции это событие будет неактуально);

  • hangup — прекращение вызова на внутреннем номере – отправителе события.

Всем специальным внутренним номерам (type = IVR или queue) рекомендуется добавлять только событие “hangup”.

Для отображения готовности агента очереди принять вызов используются данные события агента очереди (available — готов к приему звонков из очереди, logged_out — не будет принимать звонки из очереди). Данные событий могут использоваться в реал-тайм мониторинге.

Параметры событий, используемые для анализа

Полный список параметров событий и подробное их описание указаны в разделе “События внутреннего номера”.

Имя

Тип

Описание

Имя

Тип

Описание

CallerIDNum

string

Номер звонящего, по которому по умолчанию регистрируются входящие вызовы (flow события — dial-in)

CalledNumber

string

Вызываемый номер:

  • в случае входящего вызовы (flow события — dial-in) — внутренний номер, на который поступил входящий вызов по данному событию;

  • в случае исходящего вызова (flow события — dial-out) — внешний вызываемый номер, по которому по умолчанию регистрируются исходящие вызовы

CallerExtension

string

Внутренний номер — инициатор исходящего вызова (flow события — dial-out). Имеет формат вида префикс_клиента*имя_внутреннего_номера@имя_домена_АТС, указываем только префикс_клиента*имя_внутреннего_номера

CalledDID

string

Источник вызова (публичный номер вызываемого абонента, посредством которого вызов попал в АТС), при наличии обязательно передаем, т.к. фиксируется в интеграции

Bridged

string

Параметр указывает на то, был ли вызов глобально в рамках всей АТС принят пользователем внутреннего телефонного номера. Если принят сотрудником, то bridged = yes, если нет, то bridged = no (ответа на входящий вызов посредством обычного внутреннего телефонного номера не произошло). Данный параметр передается только в событиях “hangup” от специальных внутренних номеров типа IVR и Очередь

Transfered

string

Параметр принимает значение yes (исходящий вызов произошел в результате переадресации), актуально только для исходящих вызовов (flow события — dial-out) и соответствующих вызову событий “answer” и “hangup”

RemoteNumber

string

Может присутствовать только в flow события “dial-in” и указывает внешний номер, с которым связан данный вызов. Используется для понимания, с каким внешним номером произошло соединение при переводе вызова с одного внутреннего номера на другой командами перевода #1 и *2, в таких ситуациях используется вместо CallerIDNum при регистрации вызова

CallBackID

string

Идентификатор обратного вызова (ID инициации исходящего вызова через API). Добавляется в случае, если вызов генерируется от имени какого-то внутреннего номера, но соединение при этом происходит между внешним номером и каким-либо еще номером или внутренним номером, отличным от внутреннего номера – инициатора вызова. К примеру, когда скрипт заказа звонка на сайте соединяет вводимый в него номер с голосовым меню клиентской АТС

Duration

integer

Длительность вызова для каждого отдельного SubCallID в микросекундах

RecID

string

Если на внутреннем номере включена запись разговоров, то тут содержится ее идентификатор. Эквивалентно record_uuid. По нему можно получить файл записи. Имеет смысл только в событии “hangup”

CallStatus

string

Статус вызова. Успешный вызов имеет CallStatus=ANSWER, неуспешные вызовы имеют статус CallStatus=CANCEL (отменен звонящим), CallStatus=BUSY (вызываемый номер занят). Такие вызовы не должны попадать во внешнюю систему как успешные

Регистрация данных о звонках

Все события обычных внутренних телефонных номеров для событий “dial-in” и “dial-out” анализируются и в случае наличия события “answer” регистрируются по событию “hangup” и SubCallID как отдельные вызовы (вместо CallID). Таким образом удастся делить вызов в рамках АТС на отдельные плечи (call legs) — до перевода и после перевода и регистрировать их как отдельные вызовы.

Неотвеченные входящие вызовы фиксируются по наличию в событиях типа “hangup” от голосового меню и очередей параметра Bridged=no. При этом нужно помнить, что Bridged=yes — это всегда успешный входящий вызов. По нему данные должны быть зафиксированы при анализе событий “dial-in” в рамках их собственных SubCallID.

Добавление/удаление событий на внутренних номерах

Для поддержания актуального списка событий на внутренних номерах отправлять запросы на добавление/удаление событий рекомендуется в то время, когда в настройках интеграции администратор прописывает/меняет соответствие пользователей их внутренним номерам. При этом нельзя удалять либо обновлять события, не относящиеся к данной интеграции, т.к. у пользователя может быть несколько других активных интеграций.

Количество событий на одном внутреннем номере согласно стандартным допускам — 16. Потому при невозможности добавить событие нужно сообщить пользователю данную информацию с тем, чтобы он либо удалил неиспользуемые события на внутреннем номере, либо отправил запрос администратору АТС на расширения лимита событий на внутренних номерах

Фильтрация событий, полученных от АТС

Для настройки фильтрации событий, полученных от АТС, рекомендуется ознакомиться с подразделом “Данные события (EventData)”.

Если необходимо фиксировать только внешние вызовы (на внешний номер / с внешнего номера), то нужно исключить из обработки:

  • события, относящиеся к звонкам c одного внутреннего номера на другой:
    — в поле CallerNum: внутренний номер о в формате [0-9]{3,6}*[0-9]{2,4}
    — в поле CalledNum: внутренний номер в формате [0-9]{3,6}*[0-9]{2,4}

  • события, относящиеся к внутренним переадресациям:
    — в поле Transfered: "yes"
    — присутствует поле CalledExtensionID с числовым id
    — присутствует поле CallerExtensionID с числовым id

Пример события

URL в событии может быть таким: http://myintegration.com:8080/cid/807/queue/33334
где 807 — порядковый номер приложения Ringme для данной интеграции. В дальнейшем данный номер можно использовать для того, чтобы отфильтровать в логе сервера интеграций все события, относящиеся к данному пользователю;
queue — тип внутреннего номера, на котором заданo URL события. Задание разных URL позволяет удобно разделять события разных типов внутренних номеров (phone, queue или IVR);
33334 — идентификатор внутреннего номера, упрощает анализ событий.

Однако с точки зрения безопасности в общеиспользуемых интеграциях такие URL в событиях лучше не создавать, т.к. при таком URL можно, подобрав client_id и extention_id, производить массовую рассылку событий другим пользователям. Рекомендуется указывать URL вида: http://myintegration.com/ext-event/f2a8vdrfae0s1ku5d2rj3iximjf3twyz
где ext-event — тип события;
f2a8vdrfae0s1ku5d2rj3iximjf3twyz — уникальный идентификатор, который однозначно соответствует записи внутреннего номера в таблице внутренних номеров вашей интеграции.

 

← Авторизация приложения и запуск интеграции Логика событий на внутренних номерах →