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

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

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

Пример передаваемых данных можно увидеть [ниже](#chat-example). Описание параметров:


| Имя параметра    | Описание параметра                                              |
|------------------|-----------------------------------------------------------------|
| `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`        | Тип сообщения (см. [Типы и подтипы сообщений](https://webim.ru/kb/dev/basic-objects/message-types.html)). |

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

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

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

| Имя параметра  | Описание параметра                                  |
|----------------|-----------------------------------------------------|
| `ip`           | IP-адрес посетителя.                                |
| `landing_page` | [Первая просмотренная посетителем страница на сайте.](https://webim.ru/)|

## Пример передаваемых данных {: #chat-example }


```
{
  "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)
```

---

Источник: https://webim.ru/kb/dev/chat-handlers/data-description-v4.html