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 v2 messenger method im.v2.Chat.Mention.list. The list contains active members, excluding the current user, members whose membership is hidden, and hidden bots. One page, no cursor.

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
limit (query) number no 50 How many members to return, from 1 to 200. A value outside the range is clamped; the requested and applied values are echoed in meta.requestedLimit and meta.appliedLimit. Without the parameter Bitrix24 chooses the size

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.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. Arrives together with appliedLimit, only when the value was outside the 1 to 200 range
meta.appliedLimit number The applied limit value

The user object also carries other messenger fields, with camelCase keys.

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
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
404 ENTITY_NOT_FOUND Bitrix24 answered "not found"; the portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code. A chat that does not exist — 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. Bitrix24 drops hidden bots after the selection, 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, Bitrix24 adds the caller as a member, as when opening a chat. This read-intent operation is allowed for a READONLY key under the narrow exception; it does not mark messages read. The im scope and the user's Bitrix24 access still apply.

See also