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
Fieldids Typenumber[] Requiredyes DescriptionFrom 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.chatId Typenumber DescriptionID of the chat the messages belong to
Fielddata.lastId Typenumber DescriptionID of the chat's last message
Fielddata.counter Typenumber DescriptionNumber of unread messages remaining after the operation
Fielddata.viewedMessages Typearray DescriptionIDs 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
HTTP400 CodeINVALID_PARAMS Descriptionids 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
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 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
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned the NOT_FOUND code; the Bitrix24 code is in error.b24Code
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe user has no access to the chat of the messages — Bitrix24 refused with the ACCESS_DENIED code
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

See also