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

В данной статье описан механизм вызова внешних обработчиков (вебхуков) для событий, происходящих в системе Webim при работе с чатами. Этот механизм позволяет интегрировать Webim с внешними системами (CRM, биллинги и т. д.) и по сути является «обратным API»: при наступлении события Webim инициирует HTTP-запрос на указанный URL внешней системы.

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

Чтобы задействовать обработчики событий чата, в разделе Общие настройки → Интеграция панели управления укажите URL-адреса вебхуков, которые система будет вызывать при наступлении соответствующих событий.

Откройте раздел Общие настройки → Интеграция.
В блоке «Обработчики событий чата» задайте 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 — пароль.

Важно

Учётные данные в URL могут попадать в логи веб-серверов, прокси, балансировщиков и систем мониторинга. По возможности используйте защищённый контур передачи и ограничивайте доступ к логам.

Авторизация запросов к обработчику

Webim вызывает ваш обработчик по HTTP. Проверку подлинности запроса (что он исходит от Webim и данные не искажены) вы настраиваете сами; типичные варианты:

Basic Auth в URL — логин и пароль в составе адреса, как в примере выше;
Сетевые ограничения — например, белый список IP-адресов (allowlist) узлов Webim на балансировщике или файрволе;
Проверка подписи — сверка поля crc или signature и содержимого chat по алгоритму из раздела «Расчёт контрольной суммы».

Webim не подставляет отдельные заголовки вида Authorization: Bearer … или иные произвольные секреты поверх настроенного URL. При необходимости других схем (токен в path/query, mTLS и т. п.) их реализует принимающая сторона.

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

В 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, timeout_for_chat_auto_close_if_closed_by_operator и другим из статьи Список тайм-аутов;
сразу после того, как оператор нажал кнопку «Закрыть чат», если в конфигурации аккаунта включён параметр operator_closes_chat_finally. Управлять этим параметром можно через account config editor.

Подробнее о переходах между состояниями чата см. в статье Жизненный цикл чата.

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

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

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

В таблице ниже показано, какое значение присваивается новому аккаунту по умолчанию и какие значения доступны для ручной установки на данном релизе:

Версия Webim	Значение при создании аккаунта	Доступные значения для ручной установки
8.15 и ранее	`1`	`1`
8.16 – 10.4	`2`	`1`, `2`
10.5 – 10.6	`3`	`1`, `2`, `3`
10.7 и новее	`3`	`1`, `2`, `3`, `4`

Значение 4 не устанавливается автоматически при создании аккаунта. Его нужно задать вручную в настройках, если требуется подпись HMAC-SHA256 вместо MD5 (см. раздел «Расчёт контрольной суммы») и формат категорий category_ids.

Примечание

Речь идёт о версиях продукта Webim, а не о версиях API обработчиков. Продукт Webim версий 8.15 и ранее более не поддерживается. При этом все четыре значения параметра chat_event_handlers_version (1, 2, 3, 4) по-прежнему работоспособны в актуальных версиях Webim.

Различия между версиями API

Аспект	Версия `1`	Версия `2`	Версия `3`	Версия `4`
Категории чата	`category` + `subcategory` (одна пара)	`category` + `subcategory` (одна пара)	`categories` — массив пар `[категория, подкатегория]`	`category_ids` — массив числовых идентификаторов
Объект `visitor`	Плоский словарь полей посетителя	Объект `{id, fields}` (+ `channel` при наличии)	Как в версии `2`	Как в версии `2`
Поле подписи	`crc` (MD5)	`crc` (MD5)	`crc` (MD5)	`signature` (HMAC-SHA256)

Подробное описание формата данных для каждой версии см. в разделе «Документация по версиям API».

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

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

Если URL задан, но принимающая сторона недоступна, не отвечает в пределах тайм-аута запроса (10 секунд в текущей реализации) или возвращает HTTP-код ошибки, повторная отправка того же события не выполняется. Не следует рассчитывать на автоматическую повторную доставку.

Рекомендуется отвечать на запрос быстро. Webim не использует тело и код HTTP-ответа вашего обработчика как подтверждение доставки вебхука и продолжает обработку чата на своей стороне независимо от ответа. При жёстких требованиях к доставляемости ориентируйтесь на логи сервера и при необходимости уточняйте поведение у службы технической поддержки Webim.

Описание передаваемых данных

При наступлении одного из событий (chat_started, chat_assigned, chat_closed) сервер Webim выполняет HTTP-запрос методом POST на URL, указанный в соответствующем параметре *_handler_url. При этом:

используется протокол HTTP(S) (рекомендуется HTTPS);
кодировка данных — UTF-8;
устанавливается заголовок Content-Type: application/x-www-form-urlencoded;
данные о событии передаются в виде query string-параметров, несмотря на то, что тип запроса — POST;
тело запроса (body) остаётся пустым.

В запросе передаются следующие поля:

crc (для chat_event_handlers_version ниже 4) или signature (для версии 4 и выше) — контрольная сумма или цифровая подпись объекта chat. Для большинства существующих аккаунтов используется поле crc и алгоритм MD5. При chat_event_handlers_version 4 и выше поле называется signature и используется алгоритм HMAC-SHA256 с первым приватным ключом аккаунта. Подробнее см. в разделе «Расчёт контрольной суммы».
chat — данные о диалоге, сообщениях и служебной информации в формате JSON.

Содержимое поля chat

Пример передаваемых данных можно увидеть ниже. Описание параметров:

Примечание

В таблице ниже показаны поля, общие для большинства версий API. Основные различия между версиями:

Категории: в v1 и v2 передаются category + subcategory, в v3 — categories (массив пар), в v4 — category_ids (массив числовых идентификаторов).
Объект visitor: в v1 — плоский словарь полей посетителя (например, name, phone, email); в v2 и выше — объект {id, fields} с опциональным полем channel.

Подробнее см. «Различия между версиями API».

Имя параметра	Описание параметра
`category`	Категория чата, присваивается оператором (v1, v2). В v3 заменено на `categories`, в v4 — на `category_ids`.
`start_page`	Страница, на которой посетитель начал чат.
`subcategory`	Подкатегория чата, присваивается оператором (v1, v2). В v3 и v4 не используется.
`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`	Тип сообщения (см. Типы и подтипы сообщений).

Содержимое объекта operator

Имя параметра	Описание параметра
`id`	Уникальный номер оператора в системе Webim.
`email`	Email оператора.
`name`	Символьный идентификатор оператора.

Содержимое объекта visit_session

Имя параметра	Описание параметра
`ip`	IP-адрес посетителя.
`landing_page`	Страница, на которой был посетитель перед открытием чата.

Расчёт контрольной суммы

Чтобы гарантировать подлинность данных, вместе с ними передаётся контрольная сумма или цифровая подпись. Ниже всегда имеется в виду значение параметра chat_event_handlers_version, а не номер релиза Webim как таковой.

Для chat_event_handlers_version ниже 4 (поле crc, алгоритм MD5):

Формируется одна строка: сериализованное содержимое chat (как в запросе) сразу сцепляется с приватным ключом без разделителей между ними.
От этой строки берётся хэш MD5.
Результат записывается в поле crc.

Для chat_event_handlers_version 4 и выше (поле signature, алгоритм HMAC-SHA256):

Вычисляется HMAC-SHA256: в качестве ключа используется первый приватный ключ аккаунта, в качестве сообщения — содержимое chat (это не эквивалентно вычислению одного лишь SHA-256 от склеенной строки «chat + ключ»).
Полученная строка подписи записывается в поле signature.

Примеры передаваемых данных

{
   "Timestamp":"2020-06-26T19:25:57.418306Z",
   "Method":"POST",
   "RemoteAddr":"192.168.1.25",
   "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=192.168.1.30nu041fu0440u0438u0448u0435u043b
                              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": "192.168.1.30",
               "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"
      }
   }
}

Документация по версиям API

Подробное описание структуры данных, передаваемых в обработчики в зависимости от версии chat_event_handlers_version, см. в статьях:

Последнее обновление страницы: 27 марта 2026 г.