Модуль «вебхуки» используется для интеграции 3СХ со сторонними CRM системами. Он написан на C#, реализован как служба и в момент старта подключается к 3СХ. За счет этого модуль непрерывно мониторит низкоуровневую телефонную активность АТС и на основе этого мониторинга генерирует события высокого уровня:
Также модуль генерирует событие, если у какого-либо добавочного изменился один из его статусов: статус переадресации, статус глобального входа/выхода из очередей, статус входа/выхода в конкретную очередь. Кроме этого отслеживаются следующие события: появился новый добавочный номер, добавочный номер удален, в очередь добавили агента или удалили агента из очереди.
В момент наступления каждого из событий модуль отправляет https-запрос (вебхук) на заданный в ini-файле адрес с теми или иными данными о звонке или о событии изменения статуса.
Замечание: если у добавочного номера зазвонил телефон, а затем перестал звонить, но звонок не завершился (ушел на другой добавочный), то такое событие (телефон у добавочного перестал звонить, но звонок не завершился) отсутствует.
Предлагаемое решение не является полным, т.к. требует адаптации на стороне CRM. Вам необходимо собственными силами разработать прослойку межу модулем «вебхуки» и вашей CRM. Такая прослойка будет получать от нашего модуля https-запросы с информацией о звонках и на основе полученной информации будет производить необходимые действия с вашей CRM (журналирование звонков, открытие карточки контакта).
Видеопрезентация универсальной интеграции «вебхуки»
Описание данных, которые через вебхуки передаются при возникновении событий
Телефон звонит у такого-то добавочного номера
Начался разговор
Закончился звонок
ID звонка формируется следующим образом:
<дата время>_<уникальный номер звонка в рамках текущей сессии 3СХ>-<номер звена звонка>
Пример ID: 210701165649_698-2
Дата и время соответствуют моменту, когда звонок поступил на 3СХ. Звено звонка – это порядковый номер вызова в единой цепочке трансферов. Когда звонок только-только поступил на АТС, и еще никто не ответил на него, звено звонка равно 0. Как только кто-то ответил – равно 1. При каждом последующем трансфере звено звонка увеличивается на 1. У всех звонков в единой цепочке трансферов дата время и уникальный номер в рамках текущей сессии – одинаковы. Такие звонки отличаются только номером звена.
После полного завершения звонка (когда внешний абонент положил трубку) в 3СХ появляется запись разговора, или несколько записей разговоров, которые соответствуют всей цепочке трансферов, если таковые были. Запись (записи) разговоров появляются с небольшим запозданием: от нескольких миллисекунд до 1-2 секунд после того, как положили трубку. Как только это происходит, модуль «вебхуки» конвертирует wav-файл(ы) с записью (записями) в mp3-формат и помещает их в отдельную папку, из которой возможно скачивание записей через https-ссылку. Ссылка на скачивание файлов передается через соответствующий POST-запрос. Таким образом, вебхук с информацией о завершении звонка и вебхук с ссылкой на файл разговора – это разные, отдельные вебхуки.
В POST-запросе в общем случае может передаваться несколько ссылок на скачивание записи разговора. Дело в том, что у 3СХ одному разговору может соответствовать несколько звуковых файлов. Такое происходит, если говорили через мобильное приложение, и в процессе разговора связь пропадала на непродолжительное время. В этом случае каждый кратковременный разрыв связи – это начало нового файла записи.
Кроме ссылки на запись разговора POST-запрос содержит id-вызова, по которому его можно идентифицировать с событиями начала/завершения звонка. Опционально (через ini-файл) в POST-запросе можно включить передачу полной информации о завершившимся звонке. В этом случае POST-запрос будет содержать туже информацию (помимо ссылки на скачивание записи), что и событие о завершении звонка.
Записи разговоров в mp3-формате хранятся в отдельной паке необходимое количество дней (соответствующий параметр задается в ini-файле службы). По ночам записи, срок хранения которых истек, автоматически удаляются службой.
Через несколько секунд после отправки записи разговора появляются результаты речевой аналитики: полный текст разговора и его краткое резюме. Они также отправляются в соответствующем POST-запросе. Речевая аналитика работает через сервисы Яндекса. Опция требует дополнительной оплаты помимо базовой стоимости интеграции, а также регулярной оплаты сервисов Яндекса.
За расчетом стоимости модуля обращайтесь в нашу компанию.
The "webhooks" module is used to integrate 3CX with third-party CRM systems. It is written in C#, implemented as a service, and connects to 3CX at startup. Due to this, the module continuously monitors low-level telephone activity of the PBX and, based on this monitoring, generates high-level events:
The module also generates an event if one of the statuses of any extension has changed: forwarding status, global queue entry/exit status, and specific queue entry/exit status. In addition, the following events are tracked: a new extension has appeared, an extension has been deleted, an agent has been added to the queue, or an agent has been removed from the queue.
At the moment of each event, the module sends an https request (webhook) to the address specified in the ini file with certain data about the call or status change event.
Note: if the extension number's phone rang and then stopped ringing, but the call did not end (went to another extension), then such an event (the extension's phone stopped ringing, but the call did not end) is missing.
The proposed solution is not complete, since it requires adaptation on the CRM side. You need to develop a layer between the "webhooks" module and your CRM on your own. Such a layer will receive https requests from our module with information about calls and, based on the information received, will perform the necessary actions with your CRM (call logging, opening a contact card).
Video presentation of the universal integration "webhooks"
Description of data that is transmitted via webhooks when events occur
The phone rings at such and such extension
event = ringing
callerid = External number from which the call came
did = External number to which the call came (DID rule)
user = Extension number the phone is ringing at
usertype = ext / queue / other (user extension / queue / other)
id = Unique call id (string value). If the call came to the queue and the phone rings sequentially or simultaneously at several managers, then they will all have the same id.
Call started
event = hangupincoming / hangupoutgoing (Incoming or outgoing call)
callerid = External number participating in the call
user = Internal number participating in the call
did = If the call is incoming, then the external number the call was received on (DID rule)
trtype = NotDef / Blind / Accomp (How the call was received: 1) regular call, 2) call received via blind transfer, 3) call received via accompanying transfer)
id = Unique call id (string value)
Call ended
event = incoming / outgoing (Incoming or outgoing call)
callerid = External number
user = Internal number. If the call is missed and terminated at the queue level, then this will be the queue extension number
did = External number the call was received on (DID rule)
finishtype = Ok / Missed (How the call was completed: successfully (there was a conversation) or unsuccessfully (i.e. during an outgoing call they called, but no one picked up the phone at the other end, and during an incoming call - no one answered the call at the 3CX side))
transfer = false / true (Whether the call was completely completed, or whether it was transferred to another extension)
title = Detailed information about the call in the form of a phrase, which in addition to the above includes: a) the name of the DID rule for the incoming call; b) if the call was terminated at the queue level, whether a callback was ordered; c) call duration
id = Unique call id (string value)
The call ID is formed as follows:
<date time>_<unique call number within the current 3CX session>-<call link number>
Example ID: 210701165649_698-2
The date and time correspond to the moment when the call was received by 3CX. The call link is the ordinal number of the call in a single chain of transfers. When the call has just arrived at the PBX, and no one has answered it yet, the call link is equal to 0. As soon as someone has answered, it is equal to 1. With each subsequent transfer, the call link increases by 1. All calls in a single chain of transfers have the same date, time, and unique number within the current session. Such calls differ only in the link number.
After the call is completely finished (when the external subscriber hangs up), a call recording or several call recordings appear in 3CX that correspond to the entire chain of transfers, if any. The call recording(s) appear with a slight delay: from a few milliseconds to 1-2 seconds after the phone is hung up. As soon as this happens, the "webhooks" module converts the wav file(s) with the recording(s) to mp3 format and places them in a separate folder, from which it is possible to download the recordings via an https link. The link to download the files is transmitted via the corresponding POST request. Thus, a webhook with information about the end of a call and a webhook with a link to the call file are different, separate webhooks.
In general, a POST request can transmit several links to download a call recording. The fact is that in 3CX, one call can correspond to several audio files. This happens if you are talking via a mobile app and the connection is lost for a short time during the conversation. In this case, each short-term disconnection is the beginning of a new recording file.
In addition to the link to the conversation recording, the POST request contains the call ID, by which it can be identified with the call start/end events. Optionally (via the ini file), you can enable the transfer of full information about the completed call in the POST request. In this case, the POST request will contain the same information (in addition to the link to download the recording) as the call end event.
Conversation recordings in mp3 format are stored in a separate package for the required number of days (the corresponding parameter is specified in the service's ini file). At night, recordings whose storage period has expired are automatically deleted by the service.
A few seconds after sending the conversation recording, the results of speech analytics appear: the full text of the conversation and its short summary. They are also sent in the corresponding POST request. Speech analytics works through Yandex services. The option requires additional payment in addition to the basic cost of integration, as well as regular payment for Yandex services.
For calculation of the cost of the module, contact our company.