## Get chat configuration

`GET /v1/chats/configuration`

Gets available messenger capabilities, permissions for list actions and initial unread data for the current user.

The method requires the `im` scope and write access: getting configuration may create the user's system folders. No query parameters are accepted.

## Examples

### curl — personal key

```bash
curl https://vibecode.bitrix24.com/v1/chats/configuration \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl https://vibecode.bitrix24.com/v1/chats/configuration \
  -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/configuration', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const body = await res.json()
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/configuration', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const body = await res.json()
```

## Response fields

Unknown and invalid fields are omitted from the response. An invalid current-user record is represented as `legacyCurrentUser: null`. A missing field does not mean `false`, and a missing block does not mean an empty list.

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on success |
| `data.features` | object | Known messenger capabilities |
| `data.features.chatThreads` | boolean | Discussion threads are available |
| `data.features.messagesAutoDelete` | boolean | Message auto-delete is available |
| `data.features.chatGuests` | boolean | Chat guests are available |
| `data.features.chatFolders` | boolean | Chat folders are available. While the value is `false`, `data.folders.list` is empty |
| `data.featureOptions` | object | Known list settings |
| `data.featureOptions.isFolderScopedPinsAvailable` | boolean | Pins apply within individual folders |
| `data.featureOptions.isChatFolderAllAvailable` | boolean | The "All" folder is available |
| `data.featureOptions.isFolderMuteAvailable` | boolean | Muting folder notifications is available |
| `data.folders` | object | Folders and their limits. Omitted when Bitrix24 does not send them |
| `data.folders.list` | array | Folders in the same order and shape as `folders` in [chat folders](/docs/chats/discovery/folders) |
| `data.folders.limits.maxPinnedChats` | number | Non-negative integer limit on the number of pins |
| `data.permissions.byChatType` | object | Minimum roles for actions by chat type. `default` is the rule for other types |
| `data.permissions.byChatType.*.pinChat` | string | Role for pinning: `none`, `guest`, `member`, `manager` or `owner` |
| `data.permissions.byChatType.*.hideChat` | string | Role for hiding, with the same allowed values |
| `data.permissions.byChatType.*.mute` | string | Role for notifications, with the same allowed values |
| `data.counters` | object | Unread counters. Omitted when Bitrix24 does not send them |
| `data.counters.userCounters` | array | Rows in the same shape as in [unread counters](/docs/chats/discovery/counters) |
| `data.anchors` | object | Unread mentions and reactions. Omitted when Bitrix24 does not send them |
| `data.anchors.anchors` | array | Rows in the same shape as in [unread anchors](/docs/chats/messages/anchors-list) |
| `data.preloadedEntities.legacyCurrentUser` | object \| null | Initial information about the current user. `null` means the supplied record is invalid |
| `data.preloadedEntities.legacyCurrentUser.id` | number | Positive ID of [the current user](/docs/entities/users/me) |
| `data.preloadedEntities.legacyCurrentUser.type` | string | Known user type: `user`, `extranet`, `collaber` or `guest`. The field is omitted if the type is unknown |
| `data.folderActions` | object | Platform permission to execute folder actions |
| `data.folderActions.mute` | boolean | The platform permits both muting and unmuting folder notifications |
| `data.folderActions.readAll` | boolean | The platform permits marking the folder as read |

## Response example

```json
{
  "success": true,
  "data": {
    "features": {"chatThreads": true, "messagesAutoDelete": false, "chatFolders": true},
    "counters": {"userCounters": [{"chatId": 1945, "counter": 2, "parentChatId": 0, "isMuted": false, "isMarkedAsUnread": false, "recentSections": ["default"]}]},
    "folders": {"list": [{"id": 1, "type": "system", "definition": {"recentSection": "default"}}], "limits": {"maxPinnedChats": 45}},
    "anchors": {"anchors": [{"chatId": 1945, "messageId": 846, "fromUserId": 7, "type": "reaction", "subType": "like", "parentChatId": 0, "parentMessageId": 0, "recentSections": ["chat"]}]},
    "featureOptions": {"isFolderScopedPinsAvailable": true, "isChatFolderAllAvailable": true, "isFolderMuteAvailable": false},
    "permissions": {"byChatType": {"default": {"pinChat": "member", "hideChat": "member", "mute": "member"}}},
    "preloadedEntities": {"legacyCurrentUser": {"id": 6, "type": "user"}},
    "folderActions": {"mute": true, "readAll": true}
  }
}
```

## Error response example

400 — the unknown query parameter `extra` was passed:

```json
{"success": false, "error": {"code": "INVALID_PARAMS", "message": "Query parameter `extra` is not accepted by GET /v1/chats/configuration. It takes no query parameters."}}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | A query parameter was passed |
| 403 | `SCOPE_DENIED` | The key does not have the `im` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key permits reads only |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 refused access |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request. Its code is preserved in `error.b24Code` |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 credentials |

For common API errors, see [Errors](/docs/errors).

## Known specifics

Permission in `folderActions` does not replace Bitrix24 account capabilities or user permissions. For example, with `folderActions.mute: true` and `isFolderMuteAvailable: false`, muting folder notifications is unavailable.

The `counters`, `folders` and `anchors` blocks come in the shapes of their own methods; a block Bitrix24 did not send is absent from the response. Only the current user's ID and known type from the Bitrix24 configuration are returned. Match the ID to the user on whose behalf the request is made. People lists, contact details, arbitrary settings and credentials are not returned. The response has `Cache-Control: private, no-store`.

## See also

- [Chat folders](/docs/chats/discovery/folders)
- [Pin a chat](/docs/chats/management/pin)
- [Unread counters](/docs/chats/discovery/counters)
