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
dialogId (path) string yes — Dialog 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
format (query) string no — v2 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
messageId number no Mark 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
success boolean Always true on success
data.dialogId string Dialog ID from the request
data.chatId number Numeric chat ID
data.lastId number ID of the last read message
data.counter number Number of unread messages remaining after the operation
data.viewedMessages array The 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
404 DIALOG_NOT_FOUND_OR_NO_ACCESS The dialog does not exist or you do not have access to it
400 INVALID_PARAMS The v2 mode only: a body field, including messageId, or a query parameter other than format
422 BITRIX_ERROR Bitrix24 returned an error (text in the message field). The Bitrix24 code is in error.b24Code
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error
502 ME_ALIAS_RESOLUTION_FAILED The v2 mode only: failed to resolve the user when using the me alias
403 BITRIX_ACCESS_DENIED The v2 mode only: the chat does not exist or you do not have access to it
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