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

Сообщения

Читайте, отправляйте, редактируйте и удаляйте сообщения, отмечайте их прочитанными и загружайте переписку из нескольких диалогов одним запросом.

Скоуп: im | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Чтение сообщений

GET /v1/chats/:dialogId/messages

Возвращает сообщения диалога с поддержкой постраничной загрузки через курсор. Алиас me в качестве dialogId адресует личный диалог текущего пользователя — подробнее в Обзоре чатов.

Параметры

Параметр Тип Обяз. По умолч. Описание
dialogId (path) string да — ID диалога: числовой ID пользователя для личных сообщений, chatXXX для групповых. Специальный алиас me — личный диалог текущего пользователя
limit (query) number нет 50 Количество сообщений на странице, принимается до 200. Облачный Битрикс24 возвращает не больше 50 записей за вызов — см. «Известные особенности»
lastId (query) number нет — Курсор для загрузки более старых сообщений: вернуть сообщения с ID меньше указанного
firstId (query) number нет — Курсор для загрузки более новых сообщений: вернуть сообщения с ID больше указанного

Примеры

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

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

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

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

const { success, data } = await res.json()
console.log('Сообщения:', data.messages)
console.log('Участники:', data.users)

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

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

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.chatId number ID чата
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[].uuid string|null Уникальный идентификатор сообщения (задаётся отправителем)
data.messages[].replaces array Список ID замещённых сообщений
data.messages[].params array|object Дополнительные параметры сообщения (форматирование, системные метки)
data.messages[].disappearingDate string|null Дата автоудаления сообщения (ISO 8601) или null
data.users array Участники диалога с профилями
data.users[].id number ID пользователя
data.users[].name string Отображаемое имя
data.users[].active boolean Активен ли пользователь на портале
data.files array Файлы, прикреплённые к сообщениям
meta.requestedLimit number Переданный limit до срезания. Присутствует вместе с appliedLimit, только когда переданное значение вышло за диапазон от 1 до 200
meta.appliedLimit number Применённое после срезания значение limit

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

JSON 
{
  "success": true,
  "data": {
    "chatId": 42,
    "messages": [
      {
        "id": 1001,
        "chatId": 42,
        "authorId": 5,
        "date": "2026-06-05T10:00:00+03:00",
        "text": "Добрый день! Как дела?",
        "unread": false,
        "uuid": null,
        "replaces": [],
        "params": [],
        "disappearingDate": null
      },
      {
        "id": 1002,
        "chatId": 42,
        "authorId": 7,
        "date": "2026-06-05T10:01:00+03:00",
        "text": "Всё хорошо, спасибо.",
        "unread": true,
        "uuid": null,
        "replaces": [],
        "params": [],
        "disappearingDate": null
      }
    ],
    "users": [
      {
        "id": 5,
        "active": true,
        "name": "Иван Петров",
        "firstName": "Иван",
        "lastName": "Петров",
        "workPosition": "Менеджер",
        "color": "#3bc8f5",
        "gender": "M",
        "bot": false,
        "type": "user"
      }
    ],
    "files": []
  }
}

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

422 — диалог не найден или нет доступа:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Access denied"
  }
}

Ошибки

HTTP Код Описание
422 BITRIX_ERROR Битрикс24 вернул ошибку — диалог не найден или нет доступа (текст в поле message)
404 ENTITY_NOT_FOUND Битрикс24 вернул ошибку NOT_FOUND
502 BITRIX_UNAVAILABLE Битрикс24 недоступен или вернул ошибку сервера
502 ME_ALIAS_RESOLUTION_FAILED Не удалось определить пользователя при использовании алиаса me
403 SCOPE_DENIED Ключу не хватает скоупа im
401 TOKEN_MISSING Не передан X-Api-Key или не настроены токены

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

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

Пагинация через курсор. Эндпоинт использует курсорную пагинацию, а не смещение по номеру страницы. Для загрузки более старых сообщений передайте lastId равным наименьшему id из последнего ответа. Для загрузки более новых — передайте firstId равным наибольшему id.

Потолок облачного Битрикс24 — 50 сообщений за вызов. Параметр limit принимает значения до 200, но облачный Битрикс24 возвращает не больше 50 записей за вызов независимо от переданного значения. Коробочные порталы могут отдавать больше. Историю глубже 50 сообщений читайте курсором lastId — страница за страницей.

Порядок сообщений. Сообщения возвращаются в порядке убывания — от новых к старым.

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