## Membership check

`GET /v1/chats/:dialogId/users/membership`

Checks which of the listed users are members of the chat — the v2 messenger method `im.v2.Chat.Member.checkMembership`. One request answers the question for a list of up to 50 users at once: for example, before inviting users to the chat or mentioning them.

## 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 |
| `userIds` (query) | string | yes | — | From 1 to 50 Bitrix24 user IDs separated by commas, for example `7,12`. Each ID is a positive integer without spaces or leading zeros. A repeated ID is allowed and counts toward the limit of 50 |

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

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/chats/chat123/users/membership?userIds=7,12" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

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

const { data } = await res.json()
console.log('Not in the chat:', data.usersNotInChat)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat123/users/membership?userIds=7,12', {
  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.usersInChat` | array | IDs of the requested users who are chat members |
| `data.usersNotInChat` | array | IDs of the requested users who are not chat members |
| `data.users` | array | Brief profiles of all requested users |
| `data.users[].id` | number | User ID |
| `data.users[].name` | string | Full name |
| `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 |

## Response example

```json
{
  "success": true,
  "data": {
    "usersInChat": [7],
    "usersNotInChat": [12],
    "users": [
      { "id": 7, "name": "John Brown", "avatar": "", "color": "#df532d", "type": "user" },
      { "id": 12, "name": "Anna Smith", "avatar": "", "color": "#1eb4aa", "type": "extranet" }
    ]
  }
}
```

## Error response example

400 — `userIds` was not sent:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`userIds` is required: 1-50 Bitrix24 user ids separated by commas (4,7), each a positive integer without spaces or leading zeros."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `userIds` was not sent, more than 50 IDs were sent, or an ID is not a positive integer; or the request has a parameter other than `userIds` or a repeated parameter. 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](/docs/errors).

## Known specifics

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

- [Users to mention](/docs/chats/members/mentionable)
- [List members](/docs/chats/members/list)
- [Add members](/docs/chats/members/add)
- [Members](/docs/chats/members)