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

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

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

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


| Имя параметра    | Описание параметра                                              |
|------------------|-----------------------------------------------------------------|
| `category`       | Категория чата, присваивается оператором.                       |
| `subcategory`    | Подкатегория чата, присваивается оператором.                    |
| `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": {
      "id": 240557,
      "email": "test@test.com",
      "name": "Administrator"
   },
   "category": "Важные чаты",
   "subcategory": null,
   "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"
   }
}
```


## Проверка контрольной суммы

Для обеспечения подлинности данных используется контрольная сумма. Алгоритм ее расчета для API обработчиков событий чата версии 2 следующий:

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

    1. Для строки, созданной на этапе 1, вычисляется контрольная сумма по алгоритму `MD5`.

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

Пример кода для проверки контрольной суммы (Python):

```
import hashlib

def check_crc(chat, account_key, sent_crc):
    m = hashlib.md5()
    m.update(chat.encode())
    m.update(account_key.encode())
    crc = m.hexdigest()

    return crc == sent_crc
```

---

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