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

Read messages

GET /v1/chats/:dialogId/messages

Returns dialog messages with cursor-based pagination. The me alias as dialogId addresses the current user's personal dialog — see more in the Chats overview.

Parameters

Parameter Type Req. Default Description
dialogId (path) string yes — Dialog ID: numeric user ID for personal messages, chatXXX for group chats. The special me alias — the current user's personal dialog
limit (query) number no 50 Number of messages per page
lastId (query) number no — Cursor to load older messages: return messages with an ID lower than the given one
firstId (query) number no — Cursor to load newer messages: return messages with an ID higher than the given one

Examples

curl — personal key

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

curl — OAuth application

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

const { success, data } = await res.json()
console.log('Messages:', data.messages)
console.log('Participants:', data.users)

JavaScript — OAuth application

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

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

Response fields

Field Type Description
success boolean Always true on success
data.chatId number Chat ID
data.messages array Array of messages
data.messages[].id number Message ID
data.messages[].chatId number ID of the chat the message belongs to
data.messages[].authorId number Message author ID. 0 — system message
data.messages[].date string Sent date (ISO 8601)
data.messages[].text string Message text
data.messages[].unread boolean Not read by the current user
data.messages[].uuid string|null Unique message identifier (set by the sender)
data.messages[].replaces array List of replaced message IDs
data.messages[].params array|object Additional message parameters (formatting, system markers)
data.messages[].disappearingDate string|null Message auto-deletion date (ISO 8601) or null
data.users array Dialog participants with profiles
data.users[].id number User ID
data.users[].name string Display name
data.users[].active boolean Whether the user is active in the Bitrix24 account
data.files array Files attached to messages

Response example

JSON 
{
  "success": true,
  "data": {
    "chatId": 42,
    "messages": [
      {
        "id": 1001,
        "chatId": 42,
        "authorId": 5,
        "date": "2026-06-05T10:00:00+00:00",
        "text": "Good afternoon! How are you?",
        "unread": false,
        "uuid": null,
        "replaces": [],
        "params": [],
        "disappearingDate": null
      },
      {
        "id": 1002,
        "chatId": 42,
        "authorId": 7,
        "date": "2026-06-05T10:01:00+00:00",
        "text": "All good, thanks.",
        "unread": true,
        "uuid": null,
        "replaces": [],
        "params": [],
        "disappearingDate": null
      }
    ],
    "users": [
      {
        "id": 5,
        "active": true,
        "name": "John Brown",
        "firstName": "John",
        "lastName": "Brown",
        "workPosition": "Manager",
        "color": "#3bc8f5",
        "gender": "M",
        "bot": false,
        "type": "user"
      }
    ],
    "files": []
  }
}

Error response example

422 — dialog not found or no access:

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

Errors

HTTP Code Description
422 BITRIX_ERROR Bitrix24 returned an error — dialog not found or no access (text in the message field)
404 ENTITY_NOT_FOUND Bitrix24 returned a NOT_FOUND error
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error
502 ME_ALIAS_RESOLUTION_FAILED Failed to resolve the user when using the me alias
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

Cursor-based pagination. The endpoint uses cursor pagination, not page-number offset. To load older messages, pass lastId equal to the smallest id from the last response. To load newer ones, pass firstId equal to the largest id.

Message order. Messages are returned in descending order — from newest to oldest.

See also