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

Users to mention

GET /v1/chats/:dialogId/users/mentionable

Returns the chat members the current user can mention with @. The list contains active members, excluding the current user, members whose membership is hidden, and hidden bots.

Parameters

Parameter Type Required Default Description
dialogId (path) string yes — Dialog ID: chatXXX for a group chat, a user ID for a direct dialog, or the me alias. chatXXX is the id field of a recent dialogs row, a user ID comes from the user list
limit (query) number no 50 How many members to return, from 1 to 200. A value outside the range is clamped, and the requested and applied values are returned in meta.requestedLimit and meta.appliedLimit. If omitted, the Bitrix24 account default of 50 applies

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

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/chat123/users/mentionable?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/chat123/users/mentionable?limit=20" \
  -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/chat123/users/mentionable?limit=20', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Can be mentioned:', data.users.map((u) => u.name))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat123/users/mentionable?limit=20', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data object Result object
data.users array Members who can be mentioned
data.users[].id number User ID
data.users[].name string Full name
data.users[].firstName string First name
data.users[].lastName string Last name
data.users[].workPosition string Job title
data.users[].avatar string Avatar URL. An empty string when no avatar is set
data.users[].color string Avatar color in hexadecimal format
data.users[].type string User type: user, extranet, bot and others
data.users[].bot boolean The user is a bot
data.users[].extranet boolean An external user
data.users[].status string Presence status, for example online
data.users[].lastActivityDate string Time of the last activity (ISO 8601)
data.users[].absent boolean | string false or the end date of the absence
data.users[].departments array Department IDs
meta.requestedLimit number The limit that was sent. Returned together with appliedLimit, and only when the value was outside the 1 to 200 range
meta.appliedLimit number The applied limit value — only when it was clamped to a bound

The user object also carries other messenger fields.

Response example

JSON 
{
  "success": true,
  "data": {
    "users": [
      {
        "id": 7,
        "active": true,
        "name": "John Brown",
        "firstName": "John",
        "lastName": "Brown",
        "workPosition": "Designer",
        "color": "#df532d",
        "avatar": "",
        "gender": "M",
        "bot": false,
        "extranet": false,
        "status": "online",
        "lastActivityDate": "2026-09-20T10:01:00+00:00",
        "absent": false,
        "departments": [1],
        "type": "user"
      }
    ]
  }
}

Error response example

400 — limit is not a number:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`limit` must be an integer (1-200)."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS A parameter other than limit, a repeated parameter or a non-numeric limit. Checked before any call to Bitrix24
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode, and the request is not made with an employee's personal key or dialogId does not point to an existing dialog
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
404 ENTITY_NOT_FOUND Bitrix24 answered "not found". The Bitrix24 code is in error.b24Code
422 BITRIX_ERROR Bitrix24 returned an error. The Bitrix24 code is in error.b24Code. For a chat that does not exist, the code is CHAT_NOT_FOUND
502 ME_ALIAS_RESOLUTION_FAILED Failed to resolve the user when using the me alias
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

Full list of common API errors — Errors.

Known specifics

The list may be shorter than limit and incomplete. Hidden bots are filtered out after the members are fetched, so a page can be shorter than limit. There is no cursor: in a chat with more than 200 members, the list is not complete — read all members through the list of members.

The call may make you a member. If the chat allows auto-join, the call adds the current user as a member, just as opening the chat does. This read is allowed for a READONLY key under a narrow exception. The call itself does not mark messages as read. The im scope and the user's Bitrix24 permissions still apply.

See also