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

Первая страница чата

GET /v1/chats/:dialogId/messages/initial

Возвращает страницу сообщений, с которой мессенджер открывает чат. Страница строится вокруг отметки «непрочитано», а если её нет — вокруг последнего прочитанного сообщения. Нужна, чтобы открыть чат там, где пользователь остановился, без отдельного запроса самого чата. Чат вместе с закреплёнными сообщениями отдаёт загрузка чата.

Параметры

Параметр Тип Обяз. По умолч. Описание
dialogId (path) string да — ID диалога: числовой ID пользователя для личных сообщений, chatXXX для групповых. Алиас me — личный диалог текущего пользователя. Диалоги пользователя — в списке последних диалогов (GET /v1/chats/recent)
limit (query) number нет 50 Сколько сообщений взять по каждую сторону от опорного. От 1 до 200: значение вне диапазона срезается, переданное и применённое значения — в meta.requestedLimit и meta.appliedLimit
ignoreMark (query) boolean нет false true — строить страницу вокруг последнего прочитанного сообщения, не глядя на отметку «непрочитано»

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

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/chat42/messages/initial?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

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

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

const { data } = await res.json()
console.log('Сообщения:', data.messages.map((m) => m.id), 'есть старше:', data.hasPrevPage)

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

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

const { data } = await res.json()
console.log('Сообщения:', data.messages.map((m) => m.id), 'есть старше:', data.hasPrevPage)

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.messages array Сообщения страницы, от старых к новым
data.messages[].id number ID сообщения
data.messages[].chatId number ID чата
data.messages[].authorId number ID автора. 0 — системное сообщение
data.messages[].date string Дата отправки (ISO 8601)
data.messages[].text string Текст сообщения
data.messages[].unread boolean Не прочитано текущим пользователем
data.messages[].viewed boolean Просмотрено текущим пользователем
data.messages[].viewedByOthers boolean Просмотрено кем-то из участников
data.additionalMessages array Сообщения, на которые отвечают сообщения страницы, если самих их на странице нет
data.users array Авторы сообщений страницы
data.usersShort array Краткие профили пользователей страницы
data.files array Файлы сообщений страницы
data.reactions array Реакции на сообщения страницы
data.stickers array Стикеры сообщений страницы
data.forwardSource null Коллекция ленты v2, общая для ответов с сообщениями. Приходит null, в том числе когда на странице есть пересланные сообщения
data.copilot object|null Блок CoPilot той же формы, что в черновом чате CoPilot. null вне чатов CoPilot
data.tariffRestrictions.isHistoryLimitExceeded boolean История старше видимой тарифом скрыта
data.hasPrevPage boolean Есть сообщения старше страницы
data.hasNextPage boolean Есть сообщения новее страницы
meta.requestedLimit number Переданный limit, когда он вышел за диапазон от 1 до 200
meta.appliedLimit number Применённое значение limit — только если он был приведён к границе

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "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": {}
      }
    ],
    "additionalMessages": [],
    "users": [],
    "usersShort": [],
    "files": [],
    "reactions": [],
    "stickers": [],
    "tariffRestrictions": { "isHistoryLimitExceeded": false },
    "hasPrevPage": true,
    "hasNextPage": false
  }
}

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

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

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "CHAT_NOT_FOUND",
    "b24Code": "CHAT_NOT_FOUND"
  }
}

Ошибки

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

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

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

Начальная страница может менять состояние. Вызов может сделать вас участником чата, который разрешает автовступление, и выдаёт быстрый доступ к файлам Диска.

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

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

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