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

Number of pinned messages

GET /v1/chats/:dialogId/pins/count

Returns how many messages are pinned in the chat, without loading the pins themselves.

Parameters

Parameter Type Required Description
dialogId (path) string yes Dialog ID: numeric user ID for personal messages, chatXXX for group chats — the dialogId field of a recent dialogs row; a user ID comes from the user list. The special me alias refers to the current user's personal dialog (details in the Chats overview)

No query parameters are accepted: any of them is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/chats/chat42/pins/count" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/chats/chat42/pins/count" \
  -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/pins/count', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

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

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

Response fields

Field Type Description
success boolean Always true on success
data.counter number Number of pinned messages

Response example

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

Error response example

400 — a query parameter was passed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Query parameter `limit` is not accepted by GET /v1/chats/:dialogId/pins/count. It takes no query parameters."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS A query parameter was passed. Checked before any call to Bitrix24
404 ENTITY_NOT_FOUND Bitrix24 reported "not found"; the portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 returned an error; the code is in error.b24Code, for example CHAT_NOT_FOUND — there is no such chat
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY Read-only mode: the existing chat was not confirmed within the bounded window of recent dialogs, or a creating or ambiguous alias was passed. The method that would create a chat is not sent to the Bitrix24 account
403 WRITE_BLOCKED_READONLY_KEY The read in READONLY mode is not available to an application key, a management key or a key whose owner type is unconfirmed
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
502 ME_ALIAS_RESOLUTION_FAILED The me alias could not be resolved: Bitrix24 returned no ID of the current user

Full list of common API errors — Errors.

Known specifics

The request may make you a member. When the chat allows auto-join, the call may add the current user as a member, as loading a chat does. An ordinary employee's personal key in READONLY mode can perform this read. It does not mark messages read.

Only the visible history is counted. If you can see the chat history only from a certain point on — for example, you were added later without access to older messages — pins before that point are not counted.

See also