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

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

curl — OAuth application

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

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

See also