## История сессии

> **Эндпоинт включается платформой Вайбкод постепенно.** Пока он не включён на платформе, вызов возвращает `403 OPENLINES_HISTORY_DISABLED` — это признак того, что возможность ещё не активирована, а не ошибка интеграции.

`POST /v1/openlines/sessions/history`

Возвращает транскрипт последней сессии чата Открытой линии по его идентификатору: сообщения, участников и метаданные файлов одним ответом. Метод отдаёт содержимое переписки с клиентом, поэтому требует ключа со скоупом `imopenlines` и применяет модель прав Битрикс24.

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `chatId` | number \| string | да | Идентификатор чата Открытой линии. Принимается число (`2043`) и форма `chat2043`. Источник: `chatId` из [`GET /v1/chats/recent`](/docs/chats/discovery/recent) или из события бота |
| `dialogId` | string | да | Тот же чат в форме `chat2043` — альтернатива `chatId`. Достаточно одного из двух полей |

Вход только по идентификатору чата. По нему платформа берёт **последнюю** сессию этого чата — то есть транскрипт текущего диалога. Идентификатор конкретной исторической сессии на вход не принимается.

Пагинации у метода нет: транскрипт возвращается целиком одним ответом. Для постраничного чтения сообщений чата используйте [`GET /v1/chats/:dialogId/messages`](/docs/chats/messages/list).

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `sessionId` | number | Идентификатор сессии, к которой относится транскрипт |
| `chatId` | number | Идентификатор чата |
| `messages` | object[] | Сообщения по возрастанию `id` |
| `messages[].id` | number | Идентификатор сообщения |
| `messages[].senderId` | number | Отправитель (`0` — системное сообщение) |
| `messages[].recipientId` | number | Получатель |
| `messages[].date` | string | Дата, ISO 8601 |
| `messages[].text` | string | Текст сообщения |
| `messages[].textLegacy` | string | Текст в устаревшем формате разметки |
| `messages[].params` | object | Дополнительные параметры сообщения. Контейнер заполняет коннектор, и его содержимое передаётся как есть, без изменений. В нём могут оказаться контактные и CRM-данные обратившегося |
| `users` | object[] | Участники диалога |
| `users[].id` | number | Идентификатор пользователя |
| `users[].name` | string | Отображаемое имя |
| `users[].firstName` | string | Имя |
| `users[].lastName` | string | Фамилия |
| `users[].workPosition` | string | Должность |
| `users[].connector` | boolean | Признак пользователя-коннектора (клиента) |
| `files` | object[] | Файлы, приложенные к сообщениям |
| `files[].id` | number | Идентификатор файла |
| `files[].name` | string | Имя файла |
| `files[].size` | number | Размер, байты |
| `files[].urlDownload` | string | Ссылка на скачивание |
| `chats` | object[] | Метаданные чата |
| `chats[].dialogId` | string | Идентификатор диалога в форме `chat<N>` |
| `chats[].entityType` | string | Тип сущности чата (`LINES` для Открытых линий) |
| `usersMessage` | object | Карта: идентификатор чата → список идентификаторов сообщений |

## Примеры

### curl — личный ключ

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/openlines/sessions/history" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": 2043 }'
```

### Ответ

```json
{
  "success": true,
  "data": {
    "sessionId": 607,
    "chatId": 2043,
    "messages": [
      {
        "id": 88101,
        "senderId": 0,
        "recipientId": 13,
        "date": "2026-08-14T10:12:33+03:00",
        "text": "Здравствуйте, не приходит счёт",
        "textLegacy": "Здравствуйте, не приходит счёт",
        "params": {}
      }
    ],
    "users": [
      { "id": 13, "name": "Анна Соколова", "firstName": "Анна", "lastName": "Соколова", "workPosition": "Оператор", "connector": false }
    ],
    "files": [],
    "chats": [
      { "dialogId": "chat2043", "entityType": "LINES" }
    ],
    "usersMessage": { "chat2043": ["88101"] }
  }
}
```

## Ошибки

| Код | HTTP | Причина |
|-----|:----:|---------|
| `OPENLINES_HISTORY_DISABLED` | 403 | Возможность ещё не включена на платформе Вайбкод |
| `SCOPE_DENIED` | 403 | У ключа нет скоупа `imopenlines` |
| `MISSING_PARAMS` | 400 | Не передан `chatId` или `dialogId`, либо значение некорректно |
| `ENTITY_NOT_FOUND` | 404 | Для указанного чата нет сессии |
| `BITRIX_ACCESS_DENIED` | 403 | У пользователя ключа нет доступа к этому диалогу |