Обработчики событий чата
В данной статье описан механизм подключения внешних обработчиков для событий, происходящих в чате, по HTTP-интерфейсу. Обработчики позволяют настраивать интеграцию с внешними системами (CRM и прочими). При помощи вебхуков Webim отправляет системе клиента информацию об основных действиях, которые происходят в системе при обработке чатов, и данный механизм является, по сути, "обратным API".
Настройка интеграции
Для активации отправки событий требуется указать в разделе Общие настройки -> Интеграция URL, на которые Webim будет отправлять данные:
Если при обращении используется Basic Auth, то укажите данные авторизации, как в примере ниже, где username — имя пользователя, password — пароль:
https://username:password@www.company.com/handler/webim_chat_start.php
Описание событий
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 секунд. На текущий момент события выполняются асинхронно, независимо друг от друга, поэтому оригинальная последовательность событий может не соблюдаться, однако на работоспособность системы это не влияет.
Описание передаваемых данных
События отправляются на указанный адрес POST-запросом по HTTP-протоколу с заголовком "content-type": "application/x-www-form-urlencoded". На все события передаются одни и те же структуры данных, вид запросов аналогичен, различаются только состояния чата на момент отправки. Данные передаются в query string-параметрах запроса, несмотря на то что тип запроса - POST, а тело запроса (body) отправляется пустым. Поля, передаваемые в запросе:
-
crc: контрольная сумма поляchat. По умолчанию, начиная с версии 10.6, поле переименовано вsignature, а используемый алгоритм подписи изменён на более надёжныйSHA256. -
chat: данные о диалоге, сообщения и служебной информации.
Содержимое поля chat
Пример передаваемых данных можно увидеть ниже. Описание параметров:
| Имя параметра | Описание параметра |
|---|---|
category |
Категория чата, присваивается оператором. |
start_page |
Страница, на которой пользователь начал чат. |
subcategory |
Подкатегория чата, присваивается оператором. |
locale |
Язык посетителя. |
visitor |
Данные о пользователе. |
created_at |
Дата и время начала чата. |
messages |
Массив сообщений в диалоге на момент отправки события. |
department_key |
Текстовый идентификатор отдела, в который обратился посетитель. |
operator |
Данные о операторе. |
id |
Уникальный номер чата в системе Webim. |
visit_session |
Данные о сессии посетителя. |
Содержимое объекта visitor
| Имя параметра | Описание параметра |
|---|---|
fields |
Дополнительные сведения о пользователе, указываются при наличии данных. |
id |
Уникальный номер пользователя в системе Webim. |
Содержимое экземпляра объекта messages
| Имя параметра | Описание параметра |
|---|---|
created_at |
Время отправки сообщения. |
message |
Текст сообщения. |
kind |
Тип сообщения (cм. Типы и подтипы сообщений). |
Содержимое объекта operator
| Имя параметра | Описание параметра |
|---|---|
id |
Уникальный номер оператора в системе Webim. |
email |
Email оператора. |
name |
Символьный идентификатор оператора. |
Содержимое объекта visit_session
| Имя параметра | Описание параметра |
|---|---|
ip |
IP-адрес посетителя. |
landing_page |
Страница, на которой был посетитель перед открытием чата. |
Расчёт контрольной суммы
Чтобы гарантировать подлинность данных, вместе с ними передаётся контрольная сумма, которая рассчитывается по следующему алгоритму:
-
Создается строка: содержимое
chat+ приватный ключ. Между содержимым объекта и приватным ключом нет никаких символов. -
Для строки, созданной на этапе 1, высчитывается контрольная сумма по алгоритму
MD5(для версий 10.6 и выше -SHA256). -
Полученная строка записывается в
crc(для версий 10.6 и выше -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"
}
}
}