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

Anchors

An anchor is a mark the Bitrix24 messenger places for you on an unread mention or on a reaction to your message: the client uses it to show the mention counter and to jump to the right message. Two calls remove anchors — in the whole chat or on selected messages. The v2 messenger methods: im.v2.Chat.Anchor.read and im.v2.Anchor.read.

Remove chat anchors

POST /v1/chats/:dialogId/anchors/read

Removes all your anchors in the chat.

Parameters

Parameter Type Required Default Description
dialogId (path) string yes — Dialog ID: a numeric user ID for direct messages, chatXXX for group chats, me — the current user's personal dialog

No body is needed. Query parameters and body fields are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat42/anchors/read" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/anchors/read', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success } = await res.json()
console.log('Anchors removed:', success)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/anchors/read', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success } = await res.json()
console.log('Anchors removed:', success)

Remove message anchors

POST /v1/chats/anchors/read

Removes your anchors on the given messages. All messages must belong to the same chat.

Parameters

Parameter Type Required Default Description
messageIds (body) number[] yes — Message IDs: 1 to 100 items, each a positive integer

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/anchors/read" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "messageIds": [1001, 1002] }'

curl — OAuth application

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

JavaScript — personal key

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

const { success } = await res.json()
console.log('Anchors removed:', success)

JavaScript — OAuth application

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

const { success } = await res.json()
console.log('Anchors removed:', success)

Response fields

Field Type Description
success boolean Always true on success
data boolean true as returned by Bitrix24, even when there was nothing to remove

Response example

JSON 
{
  "success": true,
  "data": true
}

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
400 INVALID_PARAMS A query parameter or an extra body field; for removal by message IDs — messageIds is missing, not an array, empty, has more than 100 items or contains an item that is not a positive integer. Checked before any call to Bitrix24
404 ENTITY_NOT_FOUND Bitrix24 returned "not found"; the portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code. MESSAGES_IN_DIFFERENT_CHAT_ERROR — the messages belong to different chats
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — see access rights
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
502 ME_ALIAS_RESOLUTION_FAILED Could not resolve the current user for dialogId = me

The full list of common API errors — Errors.

Known specifics

This is a write operation, even though the method is called read. The call deletes marks, so a read-only key gets 403 WRITE_BLOCKED_READONLY_KEY before any call to Bitrix24.

There is no list of anchors. No REST method returns your anchors: the messenger receives them along with its settings on load and through events. These calls only remove marks.

Messages do not become read. Removing anchors does not move the read marker — to do that, mark the dialog as read.

See also