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

List pinned messages

GET /v1/chats/:dialogId/pins

Returns a paginated list of messages pinned in a group chat or a personal dialog.

Parameters

Parameter Type Required Default Description
ParameterdialogId (path) Typestring Requiredyes Default— 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 is the current user's personal dialog — see the Chats overview
ParameterlastId (query) Typenumber Requiredno Default— DescriptionCursor: the id of the last pin of the previous page — a pin ID, not a message ID. The boundary itself is not included
Parameterorder (query) Typestring Requiredno Defaultdesc Descriptiondesc — latest pins first, asc — earliest first
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionPins per page, from 1 to 200: a value outside the range is clamped and echoed in meta.requestedLimit and meta.appliedLimit

Any other parameter or a repeated parameter is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

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

curl — OAuth application

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

const { data } = await res.json()
const byId = new Map((data.additionalMessages ?? []).map((m) => [m.id, m]))
console.log('Pinned:', data.pins.map((p) => byId.get(p.messageId)?.text))

JavaScript — OAuth application

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

const { data } = await res.json()
const byId = new Map((data.additionalMessages ?? []).map((m) => [m.id, m]))
console.log('Pinned:', data.pins.map((p) => byId.get(p.messageId)?.text))

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.pins Typearray DescriptionPins on the page
Fielddata.pins[].id Typenumber DescriptionPin ID — the lastId cursor for the next page
Fielddata.pins[].messageId Typenumber DescriptionID of the pinned message
Fielddata.pins[].chatId Typenumber DescriptionChat ID
Fielddata.pins[].authorId Typenumber DescriptionID of the user who pinned the message
Fielddata.pins[].dateCreate Typestring DescriptionWhen the message was pinned (ISO 8601)
Fielddata.additionalMessages Typearray DescriptionThe pinned messages: id, chatId, authorId, date, text, params and other v2 message fields
Fielddata.users Typearray DescriptionUsers referenced by the pins and messages
Fielddata.files Typearray DescriptionFiles of the pinned messages
Fielddata.reactions Typearray DescriptionReactions to the pinned messages
Fielddata.tariffRestrictions Typeobject DescriptionPlan restrictions on history: isHistoryLimitExceeded
Fieldmeta.requestedLimit Typenumber DescriptionThe limit you passed, when it fell outside the 1 to 200 range
Fieldmeta.appliedLimit Typenumber DescriptionThe limit value applied — only when it was clamped to a bound

Also returned are stickers, forwardSource and copilot — v2 feed collections shared by responses that carry messages.

Response example

The main user fields are shown.

JSON 
{
  "success": true,
  "data": {
    "users": [
      {
        "id": 5,
        "active": true,
        "name": "Anna Smith",
        "firstName": "Anna",
        "lastName": "Smith",
        "avatar": "",
        "bot": false,
        "type": "user"
      }
    ],
    "additionalMessages": [
      {
        "id": 1001,
        "chatId": 42,
        "authorId": 5,
        "date": "2026-10-06T09:18:11+00:00",
        "text": "Please review the home page mockup",
        "isSystem": false,
        "uuid": null,
        "forward": null,
        "params": { "isPinned": "Y" },
        "viewedByOthers": false,
        "block": null,
        "unread": false,
        "viewed": true,
        "viewedCount": 0
      }
    ],
    "tariffRestrictions": { "isHistoryLimitExceeded": false },
    "forwardSource": null,
    "files": [],
    "copilot": null,
    "stickers": [],
    "reactions": [],
    "pins": [
      {
        "id": 1,
        "messageId": 1001,
        "chatId": 42,
        "authorId": 5,
        "dateCreate": "2026-10-06T09:18:20+00:00"
      }
    ]
  }
}

Error response example

422 — there is no such chat:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "CHAT_NOT_FOUND",
    "hint": "dialogId must be a userId (number as string) for DMs or \"chat{N}\" for group chats. Examples: \"1\" for user 1, \"chat123\" for group chat 123. Create a group chat first via POST /v1/bots/:botId/chats if needed.",
    "b24Code": "CHAT_NOT_FOUND"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionA parameter other than lastId, order, limit, a repeated parameter or an invalid value. 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 DescriptionIn READONLY mode, this read 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 pins list may make you a member. When the chat allows auto-join, reading the list may add the current user as a member, as loading a chat does. This read is available to an ordinary employee's personal key in READONLY mode. It does not mark messages as read.

There is no next-page flag. The response has no hasNextPage. A page shorter than limit is the last one.

A response without pins is shorter. For a chat without pins, only pins, users and tariffRestrictions are returned. The other collections appear with the first pin, so read them with a fallback value.

See also