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
ParameterdialogId (path) Typestring Requiredyes DescriptionDialog 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.counter Typenumber DescriptionNumber 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
HTTP400 CodeINVALID_PARAMS DescriptionA query parameter was passed. Checked before any call to Bitrix24
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 reported "not found"; the portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error; the code is in error.b24Code, for example CHAT_NOT_FOUND — there is no such chat
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionRead-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
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe read in READONLY mode is not available to an application key, a management key or a key whose owner type is unconfirmed
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionThe 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