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. Without the messageId parameter all messages are marked as read. 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

Request body fields

Field Type Req. Description
messageId number no Mark all messages up to and including the given one as read. Without the parameter — mark all messages in the dialog as read

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()

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

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 there is no access to it
422 BITRIX_ERROR Bitrix24 returned an error (text in the message field)
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

Read range. When messageId is passed, all messages with an ID from the start up to and including the given one are marked as read, not just one specific message.

See also