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

First page of a chat

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

Returns the page of messages that the messenger shows when it opens a chat. The page is built around the "unread" mark or, when there is none, around the last read message. Use it to open a chat where the user left off, without a separate request for the chat itself. The chat together with pinned messages comes from loading a chat.

Parameters

Parameter Type Required Default Description
ParameterdialogId (path) Typestring Requiredyes Default— DescriptionDialog ID: numeric user ID for personal messages, chatXXX for group chats. The me alias addresses the current user's personal dialog. The user's dialogs are in the list of recent dialogs (GET /v1/chats/recent)
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionHow many messages to take on each side of the anchor message. From 1 to 200: an out-of-range value is clamped; the passed and applied values are in meta.requestedLimit and meta.appliedLimit
ParameterignoreMark (query) Typeboolean Requiredno Defaultfalse Descriptiontrue — build the page around the last read message, ignoring the "unread" mark

Any other parameter or a repeated parameter is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/chat42/messages/initial?limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

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

const { data } = await res.json()
console.log('Messages:', data.messages.map((m) => m.id), 'has older:', data.hasPrevPage)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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('Messages:', data.messages.map((m) => m.id), 'has older:', data.hasPrevPage)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.messages Typearray DescriptionMessages on the page, from oldest to newest
Fielddata.messages[].id Typenumber DescriptionMessage ID
Fielddata.messages[].chatId Typenumber DescriptionChat ID
Fielddata.messages[].authorId Typenumber DescriptionAuthor ID. 0 — a system message
Fielddata.messages[].date Typestring DescriptionDate sent (ISO 8601)
Fielddata.messages[].text Typestring DescriptionMessage text
Fielddata.messages[].unread Typeboolean DescriptionNot read by the current user
Fielddata.messages[].viewed Typeboolean DescriptionViewed by the current user
Fielddata.messages[].viewedByOthers Typeboolean DescriptionViewed by one of the members
Fielddata.additionalMessages Typearray DescriptionMessages that the page's messages reply to, when they are not on the page themselves
Fielddata.users Typearray DescriptionAuthors of the page's messages
Fielddata.usersShort Typearray DescriptionShort profiles of the page's users
Fielddata.files Typearray DescriptionFiles of the page's messages
Fielddata.reactions Typearray DescriptionReactions to the page's messages
Fielddata.stickers Typearray DescriptionStickers of the page's messages
Fielddata.forwardSource Typenull DescriptionA collection of the v2 message history shared by responses that contain messages. Comes as null, including when the page contains forwarded messages
Fielddata.copilot Typeobject|null DescriptionThe CoPilot block, shaped as in the CoPilot draft chat. null outside CoPilot chats
Fielddata.tariffRestrictions.isHistoryLimitExceeded Typeboolean DescriptionHistory older than the plan allows is hidden
Fielddata.hasPrevPage Typeboolean DescriptionThere are messages older than the page
Fielddata.hasNextPage Typeboolean DescriptionThere are messages newer than the page
Fieldmeta.requestedLimit Typenumber DescriptionThe passed limit, when it falls outside the range from 1 to 200
Fieldmeta.appliedLimit Typenumber DescriptionThe applied limit value — only when it was clamped to a bound

Response example

JSON 
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 1001,
        "chatId": 42,
        "authorId": 5,
        "date": "2026-09-20T10:00:00+00:00",
        "text": "Please review the mockup",
        "params": {}
      },
      {
        "id": 1002,
        "chatId": 42,
        "authorId": 7,
        "date": "2026-09-20T10:01:00+00:00",
        "text": "All done",
        "params": {}
      }
    ],
    "additionalMessages": [],
    "users": [],
    "usersShort": [],
    "files": [],
    "reactions": [],
    "stickers": [],
    "tariffRestrictions": { "isHistoryLimitExceeded": false },
    "hasPrevPage": true,
    "hasNextPage": false
  }
}

Error response example

422 — the chat does not exist in the Bitrix24 account:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionA parameter other than limit and ignoreMark, a repeated parameter or an invalid value. Checked before any call to Bitrix24
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned the NOT_FOUND code. The portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error. The portal code is in error.b24Code. A missing chat lands here too: CHAT_NOT_FOUND
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionFailed to resolve the user for the me alias
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe user has no access to the chat — Bitrix24 refused with the ACCESS_DENIED code
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionLoading the first page grants quick access to Drive files, so a read-only key cannot call it. Use the message history in the v2 mode
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured

The full list of common API errors — Errors.

Known specifics

The initial page may change state. The call can make you a member of a chat that allows auto-join, and it grants quick access to Drive files.

Response keys. Keys that name fields are converted to camelCase: the FILE_ID message parameter arrives as fileId. Keys that are data stay as they are: the keys of the data.copilot.roles dictionary are role codes, and copilot_assistant arrives as copilot_assistant.

Continue in the message history. Read older messages from the message history in the v2 mode, passing lastId equal to the smallest id on the page, and newer ones with order=asc and lastId equal to the largest.

See also