لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/chats/members.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Members

View chat membership, find mention candidates and member relations, add or remove members, and assign managers.

Scope: im | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

List members

GET /v1/chats/:dialogId/users

Returns the list of dialog members.

Parameters

Parameter Type Required Default Description
ParameterdialogId (path) Typestring Requiredyes Default— DescriptionDialog identifier: chatXXX for a group chat, a user ID for the personal dialog with that user, or the alias me for the personal dialog with yourself
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionNumber of members, from 1 to 200. An out-of-range value is clamped and echoed in meta.requestedLimit and meta.appliedLimit
Parameteroffset (query) Typenumber Requiredno Default0 DescriptionOffset from the start of the list. Rejected in the v2 mode
ParameterlastId (query) Typenumber Requiredno Default— DescriptionID of the last received member — an alternative to offset for paginated traversal. Rejected in the v2 mode
ParameterskipExternal (query) Typeboolean Requiredno Default— Descriptiontrue — exclude external users (types extranet, network). Rejected in the v2 mode
Parameterformat (query) Typestring Requiredno Default— Descriptionv2 turns on the v2 mode — see "The v2 mode" below. Any other value is ignored and the response is unchanged. A repeated format is not rejected: with format=v1&format=v2 the last value wins, so the v2 mode is on, while format=v2&format=v1 returns the regular response. The bracket form format[]=v2 turns on the v2 mode when all its values are v2
ParametercursorRole (query) Typestring Requiredno Default— DescriptionThe v2 mode only: data.nextCursor.role of the previous page. Passed together with cursorRelationId
ParametercursorRelationId (query) Typenumber Requiredno Default— DescriptionThe v2 mode only: data.nextCursor.relationId of the previous page — the page starts after that membership record. Passed together with cursorRole

The v2 mode. format=v2 reads the members through the v2 messenger. data carries users — the member cards, relations — the membership records with the role owner, manager or member, and nextCursor — the cursor of the next page; the keys are in camelCase. The owner comes first, then the managers, then the members. For the next page pass cursorRole and cursorRelationId from data.nextCursor. A full page always carries a cursor, so the list ends with a page whose nextCursor is null, and that page may be empty. The mode accepts only format, limit from 1 to 200, clamped and echoed, and the cursor pair; offset, lastId and skipExternal are rejected with 400 INVALID_PARAMS. The v2 mode may make you a member: when the chat allows auto-join — a comment chat, a collab or a task chat, for example — the call adds the current user as a member, as loading a chat does. A READONLY key may use the v2 mode under two conditions: it is an employee personal key, and the chat is confirmed — chatN was passed or the personal dialog was found in the same employee's recent dialogs. The regular mode stays a plain read with no such conditions. The call does not mark messages as read.

Examples

curl — personal key

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

curl — OAuth application

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

const { success, data } = await res.json()
console.log('Members:', data.length)

JavaScript — OAuth application

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

const { success, data } = await res.json()
console.log('Members:', data.length)

curl — the v2 mode

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/chat123/users?format=v2&limit=50&cursorRole=member&cursorRelationId=77" \
  -H "X-Api-Key: YOUR_API_KEY"

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of members
Fielddata[].id Typenumber DescriptionUser ID
Fielddata[].active Typeboolean DescriptionWhether the account is active
Fielddata[].name Typestring DescriptionFull name
Fielddata[].firstName Typestring DescriptionFirst name
Fielddata[].lastName Typestring DescriptionLast name
Fielddata[].workPosition Typestring DescriptionJob position
Fielddata[].color Typestring DescriptionAvatar color
Fielddata[].avatar Typestring DescriptionAvatar URL (empty string if no avatar is set)
Fielddata[].gender Typestring DescriptionGender (M — male, F — female, empty string — not specified)
Fielddata[].birthday Typestring DescriptionBirth date (empty string if not specified)
Fielddata[].extranet Typeboolean DescriptionExternal user (type extranet)
Fielddata[].network Typeboolean DescriptionBitrix24 Network user
Fielddata[].bot Typeboolean DescriptionBot
Fielddata[].connector Typeboolean DescriptionOpen Channels user (Contact Center)
Fielddata[].status Typestring DescriptionStatus (online, away, dnd)
Fielddata[].idle Typeboolean DescriptionIdle
Fielddata[].lastActivityDate Typestring DescriptionLast activity date (ISO 8601)
Fielddata[].absent Typeboolean DescriptionAbsent according to the work calendar
Fielddata[].departments Typenumber[] DescriptionList of department IDs
Fielddata[].type Typestring DescriptionUser type (user, bot, extranet)
Fielddata.users Typearray DescriptionThe v2 mode: the member cards of the page — the same fields as the data[] elements of the regular mode
Fielddata.relations Typearray DescriptionThe v2 mode: the membership records of the page
Fielddata.relations[].id Typenumber DescriptionThe v2 mode: membership record ID
Fielddata.relations[].userId Typenumber DescriptionThe v2 mode: user ID
Fielddata.relations[].chatId Typenumber DescriptionThe v2 mode: chat ID
Fielddata.relations[].role Typestring DescriptionThe v2 mode: owner, manager or member
Fielddata.relations[].isHidden Typeboolean DescriptionThe v2 mode: whether the membership is hidden
Fielddata.nextCursor Typeobject|null DescriptionThe v2 mode: the cursor of the next page — role and relationId; null — no more pages
Fieldmeta.requestedLimit Typenumber DescriptionThe limit passed, when it was outside the range from 1 to 200
Fieldmeta.appliedLimit Typenumber DescriptionThe limit applied — only when it was clamped to a bound

Response example

Regular mode:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 42,
      "active": true,
      "name": "John Brown",
      "firstName": "John",
      "lastName": "Brown",
      "workPosition": "Manager",
      "color": "#df532d",
      "avatar": "",
      "gender": "M",
      "birthday": "",
      "extranet": false,
      "network": false,
      "bot": false,
      "connector": false,
      "status": "online",
      "idle": false,
      "lastActivityDate": "2026-06-05T09:40:32+00:00",
      "absent": false,
      "departments": [1, 47],
      "type": "user"
    },
    {
      "id": 53,
      "active": true,
      "name": "Maria Davis",
      "firstName": "Maria",
      "lastName": "Davis",
      "workPosition": "Analyst",
      "color": "#83c3f7",
      "avatar": "",
      "gender": "F",
      "birthday": "",
      "extranet": false,
      "network": false,
      "bot": false,
      "connector": false,
      "status": "away",
      "idle": false,
      "lastActivityDate": "2026-06-04T18:15:00+00:00",
      "absent": false,
      "departments": [1],
      "type": "user"
    }
  ]
}

The v2 mode, the response to the "curl — the v2 mode" request above: the page after the cursor is the last one, so nextCursor is null. The cards in users are shortened; the full set of fields is the same as in the regular mode:

JSON 
{
  "success": true,
  "data": {
    "users": [
      { "id": 42, "active": true, "name": "John Brown", "firstName": "John", "lastName": "Brown", "type": "user" },
      { "id": 53, "active": true, "name": "Maria Davis", "firstName": "Maria", "lastName": "Davis", "type": "user" }
    ],
    "relations": [
      { "id": 81, "userId": 42, "chatId": 123, "isHidden": false, "role": "member" },
      { "id": 95, "userId": 53, "chatId": 123, "isHidden": false, "role": "member" }
    ],
    "nextCursor": null
  }
}

Error response example

422 — Bitrix24 error (no access to the dialog):

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Access denied"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe v2 mode only: a parameter other than format, limit, cursorRole, cursorRelationId, a repeated parameter other than format, a non-numeric limit, one half of the cursor pair without the other, a role other than owner, manager, member, or a cursorRelationId that is not a positive integer. Checked before any call to Bitrix24
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe v2 mode: a read-only key, and the chat is not confirmed — a value other than chatN was passed and the personal dialog was not found in the same employee's recent dialog list, up to 20 pages and 4000 rows, or the alias creates a dialog. Rejected before any call to Bitrix24
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe v2 mode: a read-only key that is not an employee personal key — an application key with a user session, a management key, or a key with an unconfirmed owner
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured Bitrix24 tokens
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe v2 mode: Bitrix24 returned "not found"; the portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error — the text is in the message field (for example, no access to the dialog). In the v2 mode the portal code arrives in error.b24Code; a missing chat — CHAT_NOT_FOUND
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a server error
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionCould not resolve the me alias — the token expired or Bitrix24 is unavailable

Full list of common API errors — Errors.

Known specifics

Pagination via lastId. When sequentially traversing large chats, pass lastId from the last item of the previous response instead of offset. This approach works more reliably during concurrent changes to chat membership.

The me alias returns members of the personal dialog with yourself — that is just you. For the membership of a group chat, pass chatXXX.

See also