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

Mark as read

POST /v1/chats/:dialogId/read

Marks dialog messages as read — all of them or up to the given message.

Parameters

Parameter Type Required Default Description
ParameterdialogId (path) Typestring Requiredyes Default— DescriptionDialog ID: numeric user ID for personal messages, chatXXX for group chats. In the v2 mode the me alias is the current user's personal dialog. chatXXX is the id field of a recent dialogs row; the user ID comes from the user list
Parameterformat (query) Typestring Requiredno Default— Descriptionv2 turns on the v2 mode — see "The v2 mode" below. Any other value is ignored and the response is unchanged. A repeated format is not rejected: with format=v1&format=v2 the last value wins, so the v2 mode is on, while format=v2&format=v1 returns the legacy response. The bracket form format[]=v2 turns on the v2 mode when all its values are v2

The v2 mode. format=v2 marks the whole chat as read. data carries { chatId, lastId, counter, viewedMessages }. The mode accepts no body fields: messageId is rejected with 400 INVALID_PARAMS — to mark individual messages as read, use the POST /v1/chats/messages/read operation. Query parameters other than format are rejected too.

Request body fields

Field Type Required Description
FieldmessageId Typenumber Requiredno DescriptionMark all messages up to and including the given one as read. If omitted, all messages in the dialog are marked as read. A non-numeric value is ignored, and all messages are marked as read as well. Rejected in the v2 mode

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat42/read" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "messageId": 1002 }'

curl — OAuth application

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

JavaScript — personal key

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

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

JavaScript — OAuth application

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

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

curl — the v2 mode

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat42/read?format=v2" \
  -H "X-Api-Key: YOUR_API_KEY"

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.dialogId Typestring DescriptionDialog ID from the request
Fielddata.chatId Typenumber DescriptionNumeric chat ID
Fielddata.lastId Typenumber DescriptionID of the last read message
Fielddata.counter Typenumber DescriptionNumber of unread messages remaining after the operation
Fielddata.viewedMessages Typearray DescriptionThe v2 mode: IDs of the messages marked as read by this call

Response example

JSON 
{
  "success": true,
  "data": {
    "dialogId": "chat42",
    "chatId": 42,
    "lastId": 1002,
    "counter": 0
  }
}

Error response example

404 — dialog not found or no access:

JSON 
{
  "success": false,
  "error": {
    "code": "DIALOG_NOT_FOUND_OR_NO_ACCESS",
    "message": "Dialog does not exist or you cannot access it."
  }
}

Errors

HTTP Code Description
HTTP404 CodeDIALOG_NOT_FOUND_OR_NO_ACCESS DescriptionThe dialog does not exist or you do not have access to it
HTTP400 CodeINVALID_PARAMS DescriptionThe v2 mode only: a body field, including messageId, or a query parameter other than format
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error (text in the message field). The Bitrix24 code is in error.b24Code
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a server error
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionThe v2 mode only: failed to resolve the user when using the me alias
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe v2 mode only: the chat does not exist or you do not have access to it
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