For AI agents: markdown of this page — /docs-content-en/chats/messages/bulk.md documentation index — /llms.txt

Bulk message load

POST /v1/chats/messages/bulk

Loads messages from several dialogs in a single request. Use it to sync multiple chats without extra API calls.

Request body fields

Field Type Req. Description
dialogs array yes Array of dialogs to load. From 1 to 50 items
dialogs[].dialogId string yes Dialog ID: numeric user ID, chatXXX, or the literal me. In the response the result arrives under the value passed in the request — for me the key is "me"
dialogs[].lastId number no Cursor to load older messages
dialogs[].firstId number no Cursor to load newer messages
dialogs[].limit number no Number of messages for this dialog (no more than 200)

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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 application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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 — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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('Summary:', data.summary)
for (const [key, result] of Object.entries(data.results)) {
  console.log(`Dialog ${key}:`, result.messages.length, 'messages')
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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()

Response fields

Field Type Description
success boolean Always true on success
data.results object Map of results: key is the dialogId from the request, value is an object with messages
data.results.<dialogId>.chatId number Numeric chat ID
data.results.<dialogId>.messages array Array of dialog messages (fields as in Read messages)
data.results.<dialogId>.users array Dialog participants with profiles
data.errors object Map of errors: key is the dialogId, value is an object with a code field
data.summary.total number Total number of requested dialogs
data.summary.succeeded number Number of successfully loaded dialogs
data.summary.failed number Number of dialogs that failed

Response example

JSON 
{
  "success": true,
  "data": {
    "results": {
      "chat42": {
        "chatId": 42,
        "messages": [
          {
            "id": 1001,
            "chatId": 42,
            "authorId": 5,
            "date": "2026-06-05T10:00:00+00:00",
            "text": "Hello, team!",
            "unread": false,
            "uuid": null,
            "replaces": [],
            "params": [],
            "disappearingDate": null
          }
        ],
        "users": [
          {
            "id": 5,
            "active": true,
            "name": "John Brown",
            "firstName": "John",
            "lastName": "Brown",
            "bot": false,
            "type": "user"
          }
        ],
        "files": []
      }
    },
    "errors": {},
    "summary": {
      "total": 1,
      "succeeded": 1,
      "failed": 0
    }
  }
}

Error response example

400 — the dialogs array is missing or empty:

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

Errors

HTTP Code Description
400 INVALID_REQUEST The dialogs field is missing, empty, or an item has no dialogId
400 BATCH_LIMIT_EXCEEDED Limit exceeded: more than 50 dialogs in a single request
422 BITRIX_ERROR Bitrix24 returned an error while processing the whole batch request
502 ME_ALIAS_RESOLUTION_FAILED Failed to resolve the current user for the me literal. The whole batch is rejected
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error
403 SCOPE_DENIED The key is missing the im scope
401 TOKEN_MISSING No X-Api-Key was passed or tokens are not configured

Full list of common API errors — Errors.

Known specifics

Partial success. An error for one dialog does not stop processing of the rest. Check data.errors and data.summary.failed to detect partial failures.

50-dialog limit. Set by the Bitrix24 batch-request limit. If you need to process more dialogs, split the request into several parts.

Result keys. The keys in data.results and data.errors match the dialogId field from the request. If you passed several entries with the same dialogId, only the last match has a result.

See also