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

Read messages

POST /v1/bots/:botId/chats/:dialogId/read

Marks messages as read on behalf of the bot. Without messageId, marks all messages in the chat as read.

Parameters

Parameter Type Required Default Description
ParameterbotId (path) Typenumber Requiredyes Default— DescriptionBot ID. Bot list: GET /v1/bots
ParameterdialogId (path) Typestring Requiredyes Default— DescriptionDialog ID: numeric user ID for direct messages (user list: GET /v1/users), chatXXX for group chats — from the Create a chat response

Request fields (body)

Parameter Type Required Default Description
ParametermessageId Typenumber Requiredno Default— DescriptionMarks all messages up to and including this one as read. If omitted, all messages are marked as read. The ID comes in the message event and in the Send message response

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

const { success, data } = await res.json()
console.log('Read up to:', data.lastId)

JavaScript — OAuth application

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

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe chat's read state after the call
Fielddata.chatId Typenumber DescriptionNumeric chat ID
Fielddata.lastId Typenumber DescriptionID of the message up to which the chat is marked as read
Fielddata.counter Typenumber DescriptionNumber of messages still unread by the bot in the chat
Fielddata.viewedMessages Typenumber[] DescriptionIDs of the messages this call marked as read. The bot's own messages are not included. An empty array if there were no unread messages

Response example

JSON 
{
  "success": true,
  "data": {
    "chatId": 456,
    "lastId": 1501,
    "counter": 0,
    "viewedMessages": [1499, 1500, 1501]
  }
}

Error response example

404 — bot not found:

JSON 
{
  "success": false,
  "error": {
    "code": "BOT_NOT_FOUND",
    "message": "Bot 999 not found. Register it first via POST /v1/bots."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_BOT_ID DescriptionbotId is not a number
HTTP404 CodeBOT_NOT_FOUND DescriptionNo bot found with this ID
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot belongs to a different API key
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 error (error text in message)
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the imbot scope
HTTP410 CodeBOT_DISABLED DescriptionThe bot is disabled and does not process API calls. How to restore it — Bot disabled
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

See also