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

Mark messages as read

POST /v1/chats/messages/read

Marks the listed messages as read. All the messages must belong to one chat; the chat is determined from them, so no dialogId is needed.

Request body fields

Field Type Required Description
ids number[] yes From 1 to 100 IDs of messages in one chat — numbers or digit strings. The IDs come from the chat feed (GET /v1/chats/:dialogId/messages)

Other body fields and query parameters are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/messages/read \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [1001, 1002] }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/messages/read \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [1001, 1002] }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/read', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ids: [1001, 1002] }),
})

const { data } = await res.json()
console.log('Unread remaining:', data.counter)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/read', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ids: [1001, 1002] }),
})

const { data } = await res.json()
console.log('Unread remaining:', data.counter)

Response fields

Field Type Description
success boolean Always true on success
data.chatId number ID of the chat the messages belong to
data.lastId number ID of the chat's last message
data.counter number Number of unread messages remaining after the operation
data.viewedMessages array IDs of the messages marked by this call

Response example

JSON 
{
  "success": true,
  "data": {
    "chatId": 42,
    "lastId": 1002,
    "counter": 0,
    "viewedMessages": [1001, 1002]
  }
}

Error response example

422 — the messages belong to different chats:

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

Errors

HTTP Code Description
400 INVALID_PARAMS ids is missing or is not an array of 1 to 100 positive integers (the error names the index of the invalid element), or the request has an extra body field or a query parameter. Checked before any call to Bitrix24
422 BITRIX_ERROR Bitrix24 refused; the code is in error.b24Code: MESSAGES_IN_DIFFERENT_CHAT_ERROR — the messages belong to different chats, MESSAGE_NOT_FOUND — a message does not exist
404 ENTITY_NOT_FOUND Bitrix24 returned the NOT_FOUND code; the Bitrix24 code is in error.b24Code
403 BITRIX_ACCESS_DENIED The user has no access to the chat of the messages — Bitrix24 refused with the ACCESS_DENIED code
403 SCOPE_DENIED The key is missing the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

See also