## Загрузка вокруг сообщения `GET /v1/chats/messages/:messageId/load` Открывает чат на указанном сообщении одним запросом — как [загрузка чата](/docs/chats/messages/load), но страница строится вокруг указанного сообщения, а не вокруг последнего прочитанного. Чат определяется по сообщению, `dialogId` не нужен. ## Параметры | Параметр | Тип | Обяз. | По умолч. | Описание | |----------|-----|:-----:|-----------|---------| | `messageId` (path) | number | да | — | ID сообщения, положительное целое — поле `id` сообщения из [ленты чата](/docs/chats/messages/list), [поиска сообщений](/docs/chats/messages/search) или [загрузки чата](/docs/chats/messages/load) | | `messageLimit` (query) | number | нет | 50 | Сколько сообщений взять по каждую сторону от указанного. От 1 до 200: значение вне диапазона срезается, переданное и применённое значения — в `meta.requestedMessageLimit` и `meta.appliedMessageLimit` | | `pinLimit` (query) | number | нет | 50 | Сколько закреплённых сообщений вернуть. От 1 до 200, переданное и применённое значения — в `meta.requestedPinLimit` и `meta.appliedPinLimit` | Другие параметры и повторы отклоняются с `400 INVALID_PARAMS`. ## Примеры ### curl — личный ключ ```bash curl "https://vibecode.bitrix24.tech/v1/chats/messages/1002/load?messageLimit=20" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth-приложение ```bash curl "https://vibecode.bitrix24.tech/v1/chats/messages/1002/load?messageLimit=20" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/messages/1002/load?messageLimit=20', { headers: { 'X-Api-Key': 'YOUR_API_KEY' }, }) const { data } = await res.json() console.log('Чат:', data.chat.dialogId) console.log('Ещё раньше:', data.hasPrevPage, 'ещё позже:', data.hasNextPage) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/messages/1002/load?messageLimit=20', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { data } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | Всегда `true` при успехе | | `data.chat` | object | Карточка чата сообщения: `id`, `dialogId`, `name`, `type`, `owner`, `role`, `permissions` и другие поля | | `data.messages` | array | Указанное сообщение и соседние с ним | | `data.messages[].id` | number | ID сообщения | | `data.messages[].chatId` | number | ID чата — совпадает с `data.chat.id` | | `data.messages[].authorId` | number | ID автора — профиль по [ID пользователя](/docs/entities/users/get). `0` — системное сообщение | | `data.messages[].date` | string | Дата отправки (ISO 8601) | | `data.messages[].text` | string | Текст сообщения | | `data.pins` | array | Закреплённые сообщения | | `data.users` | array | Участники, упомянутые на странице | | `data.files` | array | Файлы сообщений страницы | | `data.reactions` | array | Реакции на сообщения страницы | | `data.hasPrevPage` | boolean | Есть сообщения старше страницы | | `data.hasNextPage` | boolean | Есть сообщения новее страницы | | `data.callInfo` | object | Контекст чата: `chatId` и `token` — звонковый токен текущего пользователя. Эндпоинт передаёт его без изменений. Не пишите его в журналы | | `meta.requestedMessageLimit` | number | Переданный `messageLimit`, когда он вышел за диапазон от 1 до 200 | | `meta.appliedMessageLimit` | number | Применённое значение `messageLimit` — только если он был приведён к границе | | `meta.requestedPinLimit` | number | Переданный `pinLimit`, когда он вышел за диапазон от 1 до 200 | | `meta.appliedPinLimit` | number | Применённое значение `pinLimit` — только если он был приведён к границе | ## Пример ответа ```json { "success": true, "data": { "chat": { "id": 42, "dialogId": "chat42", "name": "Проект", "type": "chat", "owner": 5, "role": "member" }, "messages": [ { "id": 1001, "chatId": 42, "authorId": 5, "date": "2026-09-20T10:00:00+03:00", "text": "Посмотрите макет", "params": {} }, { "id": 1002, "chatId": 42, "authorId": 7, "date": "2026-09-20T10:01:00+03:00", "text": "Всё готово", "params": {} } ], "pins": [], "users": [], "files": [], "reactions": [], "hasPrevPage": true, "hasNextPage": true } } ``` ## Пример ответа при ошибке 422 — сообщения нет на портале: ```json { "success": false, "error": { "code": "BITRIX_ERROR", "message": "MESSAGE_NOT_FOUND", "b24Code": "MESSAGE_NOT_FOUND" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `INVALID_PARAMS` | `messageId` не положительное целое, параметр вне `messageLimit` и `pinLimit`, повтор параметра или некорректное значение. Проверяется до обращения к Битрикс24 | | 404 | `ENTITY_NOT_FOUND` | Битрикс24 вернул «не найдено». Код портала — в `error.b24Code` | | 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку. Код портала — в `error.b24Code`. Сюда же приходит отсутствующее сообщение — с `MESSAGE_NOT_FOUND`, и сообщение раньше начала истории, открытой пользователю в чате, — с `MESSAGE_ACCESS_DENIED` | | 403 | `BITRIX_ACCESS_DENIED` | У пользователя нет доступа к чату сообщения — Битрикс24 отказал с кодом `ACCESS_DENIED` | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` | | 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности **Открытие чата может сделать вас участником.** Если чат сообщения разрешает автовступление, вызов добавляет текущего пользователя в участники — как [загрузка чата](/docs/chats/messages/load). Эта точечная операция чтения доступна ключу `READONLY` при наличии скоупа `im` и прав пользователя в Битрикс24. Она сама не отмечает сообщения прочитанными. **Чем отличается от сообщений вокруг сообщения.** [Сообщения вокруг сообщения](/docs/chats/messages/context) возвращают только страницу сообщений с авторами и файлами. Загрузка вокруг сообщения отдаёт ещё карточку чата, закреплённые сообщения и контекст чата — всё, чтобы открыть чат с нуля, например по ссылке на сообщение. **Дальше — лента.** Более старые сообщения читайте [лентой в режиме v2](/docs/chats/messages/list) с `lastId`, равным наименьшему `id` страницы, более новые — с `order=asc` и `lastId`, равным наибольшему. ## Смотрите также - [Загрузка чата](/docs/chats/messages/load) - [Сообщения вокруг сообщения](/docs/chats/messages/context) - [Чтение сообщений](/docs/chats/messages/list)