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

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

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

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


| Имя параметра                                               | Описание параметра                                              |
| ----------------------------------------------------------- | --------------------------------------------------------------- |
| `categories`                                                | Массив пар категорий, присваиваемых оператором.                 |
| `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
   },
   "categories": [["Обращения", 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: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 обработчиков событий чата версии 3:

        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-v3.html