Перейти к содержанию

Обработчики событий чата

В данной статье описан механизм подключения внешних обработчиков для событий, происходящих в чате, по 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 Страница, на которой был посетитель перед открытием чата.

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

Чтобы гарантировать подлинность данных, вместе с ними передаётся контрольная сумма, которая рассчитывается по следующему алгоритму:

  1. Создается строка: содержимое chat + приватный ключ. Между содержимым объекта и приватным ключом нет никаких символов.

  2. Для строки, созданной на этапе 1, высчитывается контрольная сумма по алгоритму MD5 (для версий 10.6 и выше - SHA256).

  3. Полученная строка записывается в 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"
      }
   }
}