Описание передаваемых данных API хэндлеров чата (версия 4)

Данная статья посвящена описанию формата передаваемых данных API хэндлеров чата версии 4.

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

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

Имя параметра	Описание параметра
category_ids	Идентификаторы категорий чата, присвоенных оператором.
start_page	Страница, на которой посетитель начал чат.
locale	Язык посетителя.
visitor	Данные о посетителе.
created_at	Дата и время начала чата.
messages	Массив сообщений в диалоге на момент отправки события.
department_key	Текстовый идентификатор отдела, в который обратился посетитель.
operator	Данные об операторе.
id	Уникальный номер чата в системе Webim.
visit_session	Данные о сессии посетителя.

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

Имя параметра	Описание параметра
fields	Дополнительные сведения о посетителе (например, ID посетителя, имя, телефон, email и др.). Указываются при наличии данных.
id	Уникальный номер посетителя в системе Webim.
channel	Данные о канале общения посетителя (присутствует для каналов, отличных от веб-виджета). Содержит поля id, type, user_id.

Содержимое экземпляра объекта messages

Имя параметра	Описание параметра
created_at	Время отправки сообщения.
message	Текст сообщения.
kind	Тип сообщения (см. Типы и подтипы сообщений).

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

Имя параметра	Описание параметра
id	Идентификатор оператора.
email	Email оператора.
name	Имя оператора.

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

Имя параметра	Описание параметра
ip	IP-адрес посетителя.
landing_page	Первая просмотренная посетителем страница на сайте.

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

{
  "created_at": "2023-10-18T08:41:43Z",
   "id": 1069,
   "locale": "ru",
   "department_key": "automated_department",
   "operator": {
      "email": "test@test.com",
      "name": "Administrator",
      "id": 240557
   },
   "category_ids": [11, 23, 32],
   "messages": [
      {
        "created_at": "2023-10-18T08:41:43Z",
        "kind": "for_operator",
        "message": "Посетитель открыл окно диалога со страницы Тестовая страница: https://test.com/sample-page.php Местоположение - Санкт-Петербург https://maps.google.com/maps?q=59.93863,30.31413 Браузер: Яндекс Браузер 24 Пришел с https://test.com/sanmple-page.php"
     },
     {
       "created_at": "2023-10-18T08:41:43Z",
        "kind": "visitor",
        "message": "Здравствуйте. Есть вопрос..."
     },
     {
       "created_at": "2023-10-18T08:41:44Z",
        "kind": "info",
        "message": "К сожалению, в настоящий момент все операторы заняты. Пожалуйста, подождите, Вам ответит первый освободившийся оператор, либо попробуйте обратиться позже."
     },
     {
       "created_at": "2023-10-18T08:41:58Z",
        "kind": "info",
        "message": "Оператор Administrator включился в разговор."
     },
     {
       "created_at": "2023-10-18T08:41:59Z",
        "kind": "operator",
        "message": "А у нас есть ответ!",
        "operator_id": 240557
     }
  ],
  "visitor": {
      "id": "821a40bbecca4bccb2632124f199de2c",
      "fields": {
         "name": "Степан"
      }
   },
   "visit_session": {
      "ip": "192.0.2.1",
      "landing_page": {
         "url": "https://test.com/sample-page.php"
      }
   },
   "start_page": {
      "url": "https://test.com/sample-page.php"
   }
}

Проверка цифровой подписи

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

1. Для содержимого chat вычисляется подпись по алгоритму `HMAC-SHA256`, в качестве секретного ключа используется первый из приватных ключей аккаунта.

1. Полученная строка записывается в signature.

Пример кода для проверки цифровой подписи (Python):

import hashlib
import hmac

def check_signature(chat, account_key, sent_signature):
    msg = chat.encode()
    private_key = account_key.encode()  # Ваш приватный ключ аккаунта
    hash_function = hashlib.sha256
    signature = hmac.new(key=private_key, msg=msg, digestmod=hash_function).hexdigest()

    return hmac.compare_digest(signature, sent_signature)