## 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

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

### curl — OAuth application

```bash
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](/docs/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

- [Chat members](/docs/chats/members)
- [Add members](/docs/chats/members/add)
- [Remove a member](/docs/chats/members/remove)
- [Chat management](/docs/chats/management)
- [Chats](/docs/chats)