Принцип работы обработчиков событий чата
В данной статье описан механизм вызова внешних обработчиков (вебхуков) для событий, происходящих в системе Webim при работе с чатами. Этот механизм позволяет интегрировать Webim с внешними системами (CRM, биллинги и т. д.) и по сути является «обратным API»: при наступлении события Webim инициирует HTTP-запрос на указанный URL внешней системы.
Настройка интеграции
Чтобы задействовать обработчики событий чата, в настройках аккаунта Webim необходимо указать URL-адреса вебхуков, которые система будет вызывать при наступлении соответствующих событий.
-
Откройте раздел настроек аккаунта, в котором настраиваются параметры API и интеграции.
-
В блоке «Обработчики событий чата» задайте URL для каждого нужного события (
chat_started,chat_assigned,chat_closed).
Эти URL на уровне конфигурации аккаунта соответствуют параметрам:
-
chat_started_handler_url— адрес обработчика события открытия диалога; -
chat_assigned_handler_url— адрес обработчика события назначения диалога на оператора; -
chat_closed_handler_url— адрес обработчика события окончательного закрытия диалога.
Если при обращении к внешней системе используется Basic Auth, логин и пароль можно указать прямо в URL. Например, если система находится на хосте www.company.com, а для доступа требуется имя пользователя username и пароль password, URL может выглядеть так:
https://username:password@www.company.com/handler/webim_chat_start.php
где username — имя пользователя, password — пароль.
Описание событий
В Webim выделены три типа событий чата, при наступлении которых могут вызываться внешние обработчики (вебхуки):
-
chat_started— событие наступает в момент создания чата; для каждого чата возможно только одно такое событие. -
chat_assigned— событие наступает каждый раз, когда чат назначается на конкретного оператора (в том числе при переводе между операторами). За один чат событие может произойти несколько раз. -
chat_closed— событие наступает при окончательном завершении чата; для каждого чата возможно только одно такое событие.
При наступлении одного из этих событий Webim не «отправляет событие» во внешнюю систему через отдельную шину сообщений. Вместо этого сервер Webim инициирует HTTP-запрос (вебхук) на URL, указанный в соответствующем параметре аккаунта (chat_started_handler_url, chat_assigned_handler_url или chat_closed_handler_url).
Чат считается окончательно закрытым в одном из следующих случаев:
-
по тайм-ауту
timeout_for_chat_auto_close_if_chat_is_inactive; -
по другим тайм-аутам авто-закрытия, описанным в статье Список тайм-аутов;
-
сразу после того, как оператор нажал кнопку «Закрыть чат», если в конфигурации аккаунта включён параметр
operator_closes_chat_finally.
Описание передаваемых данных
При наступлении одного из событий (chat_started, chat_assigned, chat_closed) сервер Webim выполняет HTTP-запрос методом POST на URL, указанный в соответствующем параметре *_handler_url. При этом:
-
используется протокол HTTP(S) (рекомендуется HTTPS);
-
кодировка данных —
UTF-8; -
данные о событии передаются в виде query string-параметров, несмотря на то что тип запроса —
POST; -
тело запроса (body) остаётся пустым.
В запросе передаются следующие поля:
-
signature— цифровая подпись объектаchat. Для формирования подписи используется алгоритмHMAC-SHA256, в качестве секретного ключа используется первый приватный ключ аккаунта. В версиях API для обработчиков событий ниже4это поле называетсяcrcи вычисляется по алгоритмуMD5. -
chat— данные о диалоге, сообщениях и служебной информации в формате JSON.
Содержимое поля chat
Пример передаваемых данных можно увидеть ниже. Описание параметров:
| Имя параметра | Описание параметра |
|---|---|
category |
Категория чата, присваивается оператором. |
start_page |
Страница, на которой пользователь начал чат. |
subcategory |
Подкатегория чата, присваивается оператором. |
locale |
Язык посетителя. |
visitor |
Данные о пользователе. |
created_at |
Дата и время начала чата. |
messages |
Массив сообщений в диалоге на момент отправки события. |
department_key |
Текстовый идентификатор отдела, в который обратился посетитель. |
operator |
Данные о операторе. |
id |
Уникальный номер чата в системе Webim. |
visit_session |
Данные о сессии посетителя. |
Содержимое объекта visitor
| Имя параметра | Описание параметра |
|---|---|
fields |
Дополнительные сведения о пользователе, указываются при наличии данных. |
id |
Уникальный номер пользователя в системе Webim. |
channel |
Данные о канале общения посетителя (присутствует для каналов, отличных от веб-виджета). Содержит поля id, type, user_id. |
Содержимое экземпляра объекта messages
| Имя параметра | Описание параметра |
|---|---|
created_at |
Время отправки сообщения. |
message |
Текст сообщения. |
kind |
Тип сообщения (cм. Типы и подтипы сообщений). |
Содержимое объекта operator
| Имя параметра | Описание параметра |
|---|---|
id |
Уникальный номер оператора в системе Webim. |
email |
Email оператора. |
name |
Символьный идентификатор оператора. |
Содержимое объекта visit_session
| Имя параметра | Описание параметра |
|---|---|
ip |
IP-адрес посетителя. |
landing_page |
Страница, на которой был посетитель перед открытием чата. |
Расчёт контрольной суммы
Чтобы гарантировать подлинность данных, вместе с ними передаётся контрольная сумма или цифровая подпись. Алгоритм зависит от версии API обработчиков событий чата (chat_event_handlers_version).
Для версий ниже 4 (алгоритм MD5, поле crc):
-
Создаётся строка: содержимое
chat+ приватный ключ. Между содержимым объекта и приватным ключом нет никаких символов. -
Для строки, созданной на этапе 1, вычисляется контрольная сумма по алгоритму
MD5. -
Полученная строка записывается в поле
crc.
Для версии 4 и выше (алгоритм HMAC-SHA256, поле signature):
-
Для содержимого
chatвычисляется подпись по алгоритмуHMAC-SHA256, в качестве секретного ключа используется первый из приватных ключей аккаунта. -
Полученная строка записывается в поле
signature.
Примеры передаваемых данных
{
"Timestamp":"2020-06-26T19:25:57.418306Z",
"Method":"POST",
"RemoteAddr":"95.217.58.4",
"ID":452862475,
"Headers":{
"Accept":[
"*/*"
],
"Content-Length":[
"3457"
],
"Content-Type":[
"application/x-www-form-urlencoded"
],
"Host":[
"ptsv2.com"
],
"User-Agent":[
"python-requests/2.22.0"
],
"X-Cloud-Trace-Context":[
"9f4559001f74185b93ea0227212d390e/120038278221001008"
],
"X-Google-Apps-Metadata":[
"domain=gmail.com,host=ptsv2.com"
]
},
"FormValues":{
"chat":[
"{
"category": null,
"start_page": {
"url": "https://mycompany.com"
},
"subcategory": null,
"locale": "ru",
"visitor": {
"fields": {
"name": "u041fu043eu0441u0435u0442u0438u0442u0435u043bu044c"
},
"id": "afa6083ca15a40d6aa94a8ee67407fab"
},
"created_at": "2020-06-26T19:25:52Z",
"messages": [
{
"created_at": "2020-06-26T19:25:52Z",
"message": "u041fu043eu0441u0435u0442u0438u0442u0435u043bu044c u043eu0442u043au0440u044bu043b
u043eu043au043du043e u0434u0438u0430u043bu043eu0433u0430 u0441u043e
u0441u0442u0440u0430u043du0438u0446u044b my site: https://mycompany.com
nu041cu0435u0441u0442u043eu043fu043eu043bu043eu0436u0435u043du0438u0435:
u0420u043eu0441u0441u0438u044f, u0421u0430u043du043au0442-
u041fu0435u0442u0435u0440u0431u0443u0440u0433
https://maps.google.com/maps?q=59.939037,30.315784nu0411u0440u0430u0443u0437u0435u0440:
Chrome 83nIP: https://www.nic.ru/whois/?query=31.193.122.170nu041fu0440u0438u0448u0435u043b
u0441 https://mycompany.com",
"kind": "for_operator"
},
{
"created_at": "2020-06-26T19:25:52Z",
"message": "u0427u0430u0442 u043fu043eu0441u0442u0443u043fu0438u043b u0432
u043eu0442u0434u0435u043b Test Department",
"kind": "for_operator"
},
{
"created_at": "2020-06-26T19:25:52Z",
"message": "Test Department Test Department Test Department",
"kind": "info"
},
{
"created_at": "2020-06-26T19:25:52Z",
"message": "u0414u0438u0430u043bu043eu0433
u0430u0432u0442u043eu043du0430u0437u043du0430u0447u0435u043d
u043du0430 u043eu043fu0435u0440u0430u0442u043eu0440u0430 admin",
"kind": "for_operator"
},
{
"created_at": "2020-06-26T19:25:52Z",
"message": "u041fu043eu0436u0430u043bu0443u0439u0441u0442u0430,
u043fu043eu0434u043eu0436u0434u0438u0442u0435
u043du0435u043cu043du043eu0433u043e, u043a u0412u0430u043c
u043fu0440u0438u0441u043eu0435u0434u0438u043du0438u0442u0441u044f
u043eu043fu0435u0440u0430u0442u043eu0440...",
"kind": "info"
},
{
"created_at": "2020-06-26T19:25:54Z",
"message": "sdfasdf",
"kind": "visitor"
}
],
"department_key": "test",
"operator": {
"id": 207529,
"email": "admin@hehehe.he",
"name": "admin"
},
"id": 1458,
"visit_session": {
"ip": "31.193.122.170",
"landing_page": {
"url": "https://mycompany.com"
}
}
}"
],
"crc":[
"b82177f521f8b35a88d4841b4ba7df8e"
]
},
"Body":"",
"Files":null,
"MultipartValues":null
}
Пример передаваемых данных в поле chat:
{
"category":"Обращения",
"start_page":{
"url":"https://mycompany.com"
},
"subcategory":null,
"locale":"ru",
"visitor":{
"fields":{
"phone":"+7 (999) 999-99-99",
"name":"Visitor",
"email":"noreply@webim.ru"
},
"id":"13bf13179c144c1eafdaefb0fa19a1a4"
},
"created_at":"2019-07-05T16:28:20 Z",
"messages":[
{
"created_at":"2019-07-05T16:28:20 Z",
"message":"Добрый день!",
"kind":"visitor"
}
],
"department_key":"helpdesk",
"operator":{
"id":175954,
"email":"admin@admin.ru",
"name":"Administrator"
},
"id":23,
"visit_session":{
"ip":"127.0.0.1",
"landing_page":{
"url":"https://mycompany.com"
}
}
}