Для AI-агентов: markdown этой страницы — /docs-content/chats/messages/load-in-context.md индекс документации — /llms.txt

Загрузка вокруг сообщения

GET /v1/chats/messages/:messageId/load

Открывает чат на указанном сообщении одним запросом — как загрузка чата, но страница строится вокруг указанного сообщения, а не вокруг последнего прочитанного. Чат определяется по сообщению, dialogId не нужен.

Параметры

Параметр Тип Обяз. По умолч. Описание
messageId (path) number да — ID сообщения, положительное целое — поле id сообщения из ленты чата, поиска сообщений или загрузки чата
messageLimit (query) number нет 50 Сколько сообщений взять по каждую сторону от указанного. От 1 до 200: значение вне диапазона срезается, переданное и применённое значения — в meta.requestedMessageLimit и meta.appliedMessageLimit
pinLimit (query) number нет 50 Сколько закреплённых сообщений вернуть. От 1 до 200, переданное и применённое значения — в meta.requestedPinLimit и meta.appliedPinLimit

Другие параметры и повторы отклоняются с 400 INVALID_PARAMS.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/messages/1002/load?messageLimit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
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 пользователя. 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 — Ошибки.

Известные особенности

Открытие чата может сделать вас участником. Если чат сообщения разрешает автовступление, вызов добавляет текущего пользователя в участники — как загрузка чата. Эта точечная операция чтения доступна ключу READONLY при наличии скоупа im и прав пользователя в Битрикс24. Она сама не отмечает сообщения прочитанными.

Чем отличается от сообщений вокруг сообщения. Сообщения вокруг сообщения возвращают только страницу сообщений с авторами и файлами. Загрузка вокруг сообщения отдаёт ещё карточку чата, закреплённые сообщения и контекст чата — всё, чтобы открыть чат с нуля, например по ссылке на сообщение.

Дальше — лента. Более старые сообщения читайте лентой в режиме v2 с lastId, равным наименьшему id страницы, более новые — с order=asc и lastId, равным наибольшему.

Смотрите также