Принцип работы API для обработчиков событий чата

В данной статье описан механизм подключения внешних обработчиков для событий, происходящих в чате, по HTTP-интерфейсу. Обработчики позволяют настраивать интеграцию с внешними системами (CRM и прочими). При помощи вебхуков Webim отправляет системе клиента информацию об основных действиях, которые происходят в системе при обработке чатов, и данный механизм является, по сути, "обратным API".

Настройка интеграции

Для активации отправки событий требуется указать в разделе Общие настройки -> Интеграция URL, на которые Webim будет отправлять данные:

Если система, на которую Webim должен передавать данные о событиях в чатах, находится на хосте www.company.com, и при обращении используется Basic Auth, укажите данные авторизации, как в примере ниже, где username — имя пользователя, password — пароль:

https://username:password@www.company.com/handler/webim_chat_start

Описание событий

Webim отправляет три вида событий: чат начат, чат взят в обработку оператором, чат закрыт.

chat_started: событие отправляется в момент создания чата; для каждого чата возможно только одно событие.
chat_assigned: событие отправляется в момент назначения чата на оператора. Назначения могут быть несколько раз за один чат.
chat_closed: событие отправляется при окончательном завершении чата; для каждого чата возможно только одно событие.

Чат окончательно закрывается по тайм-ауту timeout_for_chat_auto_close_if_chat_is_inactive либо timeout_for_chat_auto_close_if_closed_by_operator, подробнее о тайм-аутах можно прочитать в этой статье. Если требуется окончательно закрывать чат сразу после того, как оператор нажал кнопку Закрыть чат, обратитесь в службу технической поддержки Webim с запросом активировать параметр operator_closes_chat_finally.

Узнать больше о жизненном цикле чата можно здесь.

Особенности механизма передачи данных

Когда совершается действие, подходящее под один из видов событий, Webim Server отправляет соответствующий запрос CRM-системе клиента на URL-адрес, указанный в настройках интеграции. Отправка запроса может сопровождаться задержкой до 5 секунд. На текущий момент события выполняются асинхронно, независимо друг от друга, поэтому оригинальная последовательность событий может не соблюдаться, однако на работоспособность системы это не влияет.

На данный момент существует четыре версии обработчика событий, отличающихся передаваемыми данными. За используемую версию обработчика отвечает параметр account config chat_event_handlers_version. Его значение по умолчанию зависит от актуальной на момент регистрации аккаунта версии Webim. Версионирование по умолчанию приведено в таблице ниже.

Версия Webim	Значение параметра
8.15 и ранее	`1`
8.16 - 10.4	`2`
10.5	`3`
10.6 и новее	`4`

N.B.

Версии 8.15 и более ранние не поддерживаются. Для корректной работы рекомендуется использовать новейшую версию.

Обработка ошибок

В случае, если не задан URL, куда должна быть отправлена информация о событии, отправка не будет совершена, а в логах отоборазится сообщение об ошибке.

Передаваемые объекты

События отправляются на указанный адрес POST-запросом по HTTP-протоколу с заголовком "content-type": "application/x-www-form-urlencoded". На все события передаются одни и те же структуры данных, вид запросов аналогичен, различаются только состояния чата на момент отправки. Данные передаются в query string-параметрах запроса, несмотря на то что тип запроса - POST, а тело запроса (body) отправляется пустым. Поля, передаваемые в запросе:

signature: цифровая подпись объекта chat. Для подсчёта используется алгоритм HMAC-SHA256, в качестве секретного ключа используется первый Приватный ключ из общих настроек аккаунта.

В версиях API для обработчиков событий ниже 3 поле называется crc, для подсчёта используется менее надёжный алгоритм MD5.

chat: данные о диалоге, сообщениях и служебной информации.

Подробное описание объектов и полей, передаваемых в chat можно найти в следующих статьях: