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.

Read-only key. In READONLY mode, every dialogId in the batch must point to an existing chat: its chatN, or a numeric peer ID confirmed in the same employee's recent dialogs. The me literal resolves to the current user's ID and is checked the same way. Other dialogId forms are rejected. The check scans at most 4000 raw rows of recent dialogs for the whole request. If any binding is not confirmed, the whole request returns 403 WRITE_BLOCKED_READONLY_KEY and the batch is not sent to Bitrix24. The check keeps a read from implicitly creating a chat. Bitrix24 still checks the user's access to the chat. The check's limits are described in access rights.

Request body fields

Field Type Required Description
Fielddialogs Typearray Requiredyes DescriptionArray of dialogs to load. From 1 to 50 items
Fielddialogs[].dialogId Typestring Requiredyes DescriptionDialog ID: numeric user ID, chatXXX, or the literal me. In the response, the result is keyed by the value passed in the request — for me, the key is "me"
Fielddialogs[].lastId Typenumber Requiredno DescriptionCursor to load older messages
Fielddialogs[].firstId Typenumber Requiredno DescriptionCursor to load newer messages
Fielddialogs[].limit Typenumber Requiredno DescriptionNumber 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.results Typeobject DescriptionMap of results: key is the dialogId from the request, value is an object with messages
Fielddata.results.<dialogId>.chatId Typenumber DescriptionNumeric chat ID
Fielddata.results.<dialogId>.messages Typearray DescriptionArray of dialog messages (fields as in Read messages)
Fielddata.results.<dialogId>.users Typearray DescriptionDialog participants with profiles
Fielddata.errors Typeobject DescriptionMap of errors: key is the dialogId, value is an object with a code field
Fielddata.summary.total Typenumber DescriptionTotal number of requested dialogs
Fielddata.summary.succeeded Typenumber DescriptionNumber of successfully loaded dialogs
Fielddata.summary.failed Typenumber DescriptionNumber 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
HTTP400 CodeINVALID_REQUEST DescriptionThe dialogs field is missing, empty, or an item has no dialogId
HTTP400 CodeBATCH_LIMIT_EXCEEDED DescriptionLimit exceeded: more than 50 dialogs in a single request
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error while processing the whole batch request
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionFailed to resolve the current user for the me literal. The whole batch is rejected
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a server error
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionRead-only mode: the bounded window of recent dialogs did not confirm an existing chat for one of the dialogId values, or a dialogId in another form was passed. The batch is not sent to Bitrix24
HTTP401 CodeTOKEN_MISSING DescriptionNo 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 pass several entries with the same dialogId, only the last one gets a result.

See also