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

Загрузка чата

GET /v1/chats/:dialogId/load

Открывает чат одним запросом — метод мессенджера v2 im.v2.Chat.load: карточка чата, первая страница сообщений, закреплённые сообщения, участники и файлы. Первая страница строится вокруг последнего прочитанного сообщения, а если чат помечен непрочитанным — вокруг метки. Алиас me в качестве dialogId адресует личный диалог текущего пользователя.

Параметры

Параметр Тип Обяз. По умолч. Описание
dialogId (path) string да — ID диалога: числовой ID пользователя для личных сообщений, chatXXX для групповых, me — личный диалог текущего пользователя. Берётся из поля dialogId строки последних диалогов, ID пользователя — из списка пользователей
messageLimit (query) number нет 50 Сколько сообщений взять по каждую сторону от опорного: страница — до messageLimit сообщений до него, само сообщение и до messageLimit после. От 1 до 200: значение вне диапазона срезается, эхо — meta.requestedMessageLimit и meta.appliedMessageLimit
pinLimit (query) number нет 50 Сколько закреплённых сообщений вернуть. От 1 до 200, эхо — meta.requestedPinLimit и meta.appliedPinLimit
ignoreMark (query) boolean нет false true — строить первую страницу от последнего прочитанного сообщения, не учитывая метку «непрочитанное»

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

Примеры

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

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

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/chat42/load?messageLimit=30" \
  -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/chat42/load?messageLimit=30', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Чат:', data.chat.name)
console.log('Сообщения:', data.messages.length, 'ещё раньше:', data.hasPrevPage)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/chat42/load?messageLimit=30', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Чат:', data.chat.name)
console.log('Сообщения:', data.messages.length, 'ещё раньше:', data.hasPrevPage)

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.chat object Карточка чата: id, dialogId, name, type, owner, role, entityType, entityId, permissions и другие поля
data.messages array Первая страница сообщений
data.messages[].id number ID сообщения — курсор lastId следующей страницы и messageId для сообщений вокруг сообщения
data.messages[].chatId number ID чата — совпадает с data.chat.id
data.messages[].authorId number ID автора — профиль в data.users этого же ответа или по ID пользователя. 0 — системное сообщение
data.messages[].date string Дата отправки (ISO 8601)
data.messages[].text string Текст сообщения
data.messages[].params object Дополнительные параметры сообщения, ключи в camelCase
data.pins array Закреплённые сообщения
data.users array Участники, упомянутые на странице
data.files array Файлы сообщений страницы
data.reactions array Реакции на сообщения страницы
data.hasPrevPage boolean Есть сообщения старше первой страницы
data.hasNextPage boolean Есть сообщения новее первой страницы
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": 1002,
        "chatId": 42,
        "authorId": 7,
        "date": "2026-09-20T10:01:00+03:00",
        "text": "Всё готово",
        "params": {}
      }
    ],
    "pins": [],
    "users": [],
    "files": [],
    "reactions": [],
    "hasPrevPage": true,
    "hasNextPage": false
  }
}

Пример ответа при ошибке

422 — чата нет на портале:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Указанный чат не существует",
    "hint": "dialogId must be a userId (number as string) for DMs or \"chat{N}\" for group chats. Examples: \"1\" for user 1, \"chat123\" for group chat 123. Create a group chat first via POST /v1/bots/:botId/chats if needed.",
    "b24Code": "CHAT_NOT_FOUND"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Параметр вне messageLimit, pinLimit, ignoreMark, повтор параметра или некорректное значение. Проверяется до обращения к Битрикс24
404 ENTITY_NOT_FOUND Битрикс24 вернул «не найдено»; код портала — в error.b24Code
422 BITRIX_ERROR Битрикс24 вернул ошибку; код портала — в error.b24Code. Сюда же приходит отсутствующий чат: портал отвечает CHAT_NOT_FOUND с текстом «Указанный чат не существует», и «не найдено» в нём не распознаётся, поэтому это не 404
502 ME_ALIAS_RESOLUTION_FAILED Не удалось определить пользователя при использовании алиаса me
403 BITRIX_ACCESS_DENIED У пользователя нет доступа к чату — Битрикс24 отказал с кодом ACCESS_DENIED
403 SCOPE_DENIED API-ключ не имеет скоупа im
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения: вызов может сделать владельца ключа участником чата — см. права доступа
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24

Полный список общих ошибок API — Ошибки.

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

Открытие чата может сделать вас участником. Если чат разрешает автовступление — например, чаты комментариев, коллабы, чаты задач, — вызов добавляет текущего пользователя в участники, как открытие чата в интерфейсе Битрикс24. Это поведение портала, эндпоинт его не скрывает. Поэтому вызов считается изменяющим: ключ только для чтения получает 403 WRITE_BLOCKED_READONLY_KEY. То же относится к ленте в режиме v2 и к сообщениям вокруг сообщения.

Ключи ответа. Ключи-имена полей приводятся к camelCase: параметр сообщения FILE_ID приходит как fileId. Ключи-данные остаются как есть: словарь data.copilot.roles ключуется кодом роли, и copilot_assistant приходит как copilot_assistant — тем же значением, что role у чата и сообщения в data.copilot, поэтому роль находится прямым обращением roles[role]. Поля внутри роли приводятся к camelCase как обычно.

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

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