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

POST /v1/chats/messages/bulk

Загружает сообщения из нескольких диалогов одним запросом. Используется для синхронизации нескольких чатов без лишних вызовов API.

Поля запроса (body)

Поле Тип Обяз. Описание
dialogs array да Массив диалогов для загрузки. От 1 до 50 элементов
dialogs[].dialogId string да ID диалога: числовой ID пользователя или chatXXX
dialogs[].lastId number нет Курсор для загрузки более старых сообщений
dialogs[].firstId number нет Курсор для загрузки более новых сообщений
dialogs[].limit number нет Количество сообщений для этого диалога (не более 200)

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/messages/bulk" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialogs": [
      { "dialogId": "chat42", "limit": 20 },
      { "dialogId": "chat99", "lastId": 5000 }
    ]
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/messages/bulk" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dialogs": [
      { "dialogId": "chat42", "limit": 20 },
      { "dialogId": "chat99", "lastId": 5000 }
    ]
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/messages/bulk', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dialogs: [
      { dialogId: 'chat42', limit: 20 },
      { dialogId: 'chat99', lastId: 5000 },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Итог:', data.summary)
for (const [key, result] of Object.entries(data.results)) {
  console.log(`Диалог ${key}:`, result.messages.length, 'сообщений')
}

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/messages/bulk', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dialogs: [
      { dialogId: 'chat42', limit: 20 },
      { dialogId: 'chat99', lastId: 5000 },
    ],
  }),
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.results object Словарь результатов: ключ — dialogId из запроса, значение — объект с сообщениями
data.results.<dialogId>.chatId number Числовой ID чата
data.results.<dialogId>.messages array Массив сообщений диалога (поля — как в Чтении сообщений)
data.results.<dialogId>.users array Участники диалога с профилями
data.errors object Словарь ошибок: ключ — dialogId, значение — объект с полем code
data.summary.total number Общее количество запрошенных диалогов
data.summary.succeeded number Количество успешно загруженных диалогов
data.summary.failed number Количество диалогов с ошибкой

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

JSON 
{
  "success": true,
  "data": {
    "results": {
      "chat42": {
        "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
          }
        ],
        "users": [
          {
            "id": 5,
            "active": true,
            "name": "Иван Петров",
            "firstName": "Иван",
            "lastName": "Петров",
            "bot": false,
            "type": "user"
          }
        ],
        "files": []
      }
    },
    "errors": {},
    "summary": {
      "total": 1,
      "succeeded": 1,
      "failed": 0
    }
  }
}

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

400 — массив dialogs отсутствует или пустой:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Body must contain \"dialogs\" array with at least 1 item. Each item: { dialogId, lastId?, firstId?, limit? }"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_REQUEST Поле dialogs отсутствует, пустое, или элемент не содержит dialogId
400 BATCH_LIMIT_EXCEEDED Превышено ограничение: более 50 диалогов в одном запросе
422 BITRIX_ERROR Битрикс24 вернул ошибку при обработке всего пакетного запроса
502 BITRIX_UNAVAILABLE Битрикс24 недоступен или вернул ошибку сервера
403 SCOPE_DENIED Ключу не хватает скоупа im
401 TOKEN_MISSING Не передан X-Api-Key или не настроены токены

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

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

Частичный успех. Ошибка для отдельного диалога не прерывает обработку остальных. Проверяйте data.errors и data.summary.failed для обнаружения частичных сбоев.

Ограничение 50 диалогов. Определяется лимитом пакетных запросов Битрикс24. При необходимости обработать больше диалогов разбейте запрос на несколько частей.

Ключи результата. Ключи в data.results и data.errors соответствуют полю dialogId из запроса. Если вы передали несколько записей с одинаковым dialogId, результат будет только для последнего совпадения.

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