For AI agents: markdown of this page — /docs-content-en/chats/discovery/configuration.md documentation index — /llms.txt
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
curl https://vibecode.bitrix24.com/v1/chats/configuration \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth application
curl https://vibecode.bitrix24.com/v1/chats/configuration \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — personal key
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
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 |
|---|---|---|
Fieldsuccess |
Typeboolean | Descriptiontrue on success |
Fielddata.features |
Typeobject | DescriptionKnown messenger capabilities |
Fielddata.features.chatThreads |
Typeboolean | DescriptionDiscussion threads are available |
Fielddata.features.messagesAutoDelete |
Typeboolean | DescriptionMessage auto-delete is available |
Fielddata.features.chatGuests |
Typeboolean | DescriptionChat guests are available |
Fielddata.features.chatFolders |
Typeboolean | DescriptionChat folders are available. While the value is false, data.folders.list is empty |
Fielddata.featureOptions |
Typeobject | DescriptionKnown list settings |
Fielddata.featureOptions.isFolderScopedPinsAvailable |
Typeboolean | DescriptionPins apply within individual folders |
Fielddata.featureOptions.isChatFolderAllAvailable |
Typeboolean | DescriptionThe "All" folder is available |
Fielddata.featureOptions.isFolderMuteAvailable |
Typeboolean | DescriptionMuting folder notifications is available |
Fielddata.folders |
Typeobject | DescriptionFolders and their limits. Omitted when Bitrix24 does not send them |
Fielddata.folders.list |
Typearray | DescriptionFolders in the same order and shape as folders in chat folders |
Fielddata.folders.limits.maxPinnedChats |
Typenumber | DescriptionNon-negative integer limit on the number of pins |
Fielddata.permissions.byChatType |
Typeobject | DescriptionMinimum roles for actions by chat type. default is the rule for other types |
Fielddata.permissions.byChatType.*.pinChat |
Typestring | DescriptionRole for pinning: none, guest, member, manager or owner |
Fielddata.permissions.byChatType.*.hideChat |
Typestring | DescriptionRole for hiding, with the same allowed values |
Fielddata.permissions.byChatType.*.mute |
Typestring | DescriptionRole for notifications, with the same allowed values |
Fielddata.counters |
Typeobject | DescriptionUnread counters. Omitted when Bitrix24 does not send them |
Fielddata.counters.userCounters |
Typearray | DescriptionRows in the same shape as in unread counters |
Fielddata.anchors |
Typeobject | DescriptionUnread mentions and reactions. Omitted when Bitrix24 does not send them |
Fielddata.anchors.anchors |
Typearray | DescriptionRows in the same shape as in unread anchors |
Fielddata.preloadedEntities.legacyCurrentUser |
Typeobject | null | DescriptionInitial information about the current user. null means the supplied record is invalid |
Fielddata.preloadedEntities.legacyCurrentUser.id |
Typenumber | DescriptionPositive ID of the current user |
Fielddata.preloadedEntities.legacyCurrentUser.type |
Typestring | DescriptionKnown user type: user, extranet, collaber or guest. The field is omitted if the type is unknown |
Fielddata.folderActions |
Typeobject | DescriptionPlatform permission to execute folder actions |
Fielddata.folderActions.mute |
Typeboolean | DescriptionThe platform permits both muting and unmuting folder notifications |
Fielddata.folderActions.readAll |
Typeboolean | DescriptionThe platform permits marking the folder as read |
Response example
{
"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:
{"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 |
|---|---|---|
| HTTP400 | CodeINVALID_PARAMS |
DescriptionA query parameter was passed |
| HTTP403 | CodeSCOPE_DENIED |
DescriptionThe key does not have the im scope |
| HTTP403 | CodeWRITE_BLOCKED_READONLY_KEY |
DescriptionThe key permits reads only |
| HTTP403 | CodeBITRIX_ACCESS_DENIED |
DescriptionBitrix24 refused access |
| HTTP422 | CodeBITRIX_ERROR |
DescriptionBitrix24 rejected the request. Its code is preserved in error.b24Code |
| HTTP401 | CodeTOKEN_MISSING |
DescriptionThe key has no Bitrix24 credentials |
For common API errors, see 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.