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

List members

GET /v1/chats/:dialogId/users

Returns the list of dialog members.

Parameters

Parameter Type Required Default Description
dialogId (path) string yes — Dialog identifier (chatXXX) or the alias me for the personal dialog with yourself
limit (query) number no 50 Number of members (1–200)
offset (query) number no 0 Offset from the start of the list
lastId (query) number no — ID of the last received member — an alternative to offset for paginated traversal
skipExternal (query) boolean no — true — exclude external users (types extranet, network)

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)

Response fields

Field Type Description
success boolean Always true on success
data array Array of members
data[].id number User ID
data[].active boolean Whether the account is active
data[].name string Full name
data[].firstName string First name
data[].lastName string Last name
data[].workPosition string Job position
data[].color string Avatar color
data[].avatar string Avatar URL (empty string if no avatar is set)
data[].gender string Gender (M — male, F — female, empty string — not specified)
data[].birthday string Birth date (empty string if not specified)
data[].extranet boolean External user (type extranet)
data[].network boolean Bitrix24 Network user
data[].bot boolean Bot
data[].connector boolean Open Channels user (Contact Center)
data[].status string Status (online, away, dnd)
data[].idle boolean Idle
data[].lastActivityDate string Last activity date (ISO 8601)
data[].absent boolean Absent per work calendar
data[].departments number[] List of department IDs
data[].type string User type (user, bot, extranet)

Response example

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"
    }
  ]
}

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
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no configured Bitrix24 tokens
422 BITRIX_ERROR Bitrix24 returned an error — the text is in the message field (for example, no access to the dialog)
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error
502 ME_ALIAS_RESOLUTION_FAILED Could 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