For AI agents: markdown of this page — /docs-content-en/chats/settings/general.md documentation index — /llms.txt

General settings

Read and change the user's general messenger settings — sound, theme, sending with Enter, privacy, the notification scheme and more. The response is an object whose keys are setting names; the update accepts the same names.

Read settings

GET /v1/chats/settings

Returns the general messenger settings — the v2 messenger method im.v2.Settings.General.list. Without userId, returns the key owner's settings. The portal may create a user-to-settings-preset binding even on a read, so a read-only key gets 403 WRITE_BLOCKED_READONLY_KEY before any Bitrix24 call.

Parameters

Parameter	Type	Required	Description
`userId`	number	no	ID of the user whose settings to read, a positive integer. Defaults to the key owner. Only a Bitrix24 administrator can read another user's settings

Any other query parameter is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal

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

curl — OAuth application

Terminal

curl "https://vibecode.bitrix24.com/v1/chats/settings" \
  -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/settings', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data: settings } = await res.json()
console.log('Theme:', settings.enableDarkTheme, 'Enter sends:', settings.sendByEnter)

JavaScript — OAuth application

javascript

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

const { data: settings } = await res.json()
console.log('Status:', settings.status)

Response fields

data is the settings object. Each key is a setting name; each value is a string or a boolean. Bitrix24 defines the setting names, and the set depends on the messenger version. Commonly used ones:

Field	Type	Description
`data.status`	string	User status: `online`, `dnd` or `away`. Changed through `PUT /v1/chats/settings/status`
`data.enableSound`	boolean	Messenger sounds
`data.enableBigSmile`	boolean	Large emoji in a message that consists of emoji only
`data.enableDarkTheme`	string	Theme: `auto`, `light` or `dark`
`data.sendByEnter`	boolean	`true` — a message is sent with Enter
`data.chatAlignment`	string	Message alignment in a chat
`data.pinnedChatSort`	string	Order of pinned chats
`data.notifyScheme`	string	Notification scheme: `simple` or `expert`
`data.privacySearch`	string	Who can find the user in search

Response example

Shortened — the full response contains all of the user's settings:

JSON

{
  "success": true,
  "data": {
    "status": "online",
    "enableSound": true,
    "enableBigSmile": true,
    "enableDarkTheme": "auto",
    "sendByEnter": true,
    "notifyScheme": "simple",
    "privacySearch": "all",
    "chatAlignment": "left",
    "pinnedChatSort": "byCost"
  }
}

Error response example

400 — userId is not a positive integer:

JSON

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "The query parameter `userId` must be a positive integer."
  }
}

Errors

HTTP	Code	Description
400	`INVALID_PARAMS`	`userId` is not a positive integer, or another query parameter was passed
401	`TOKEN_MISSING`	The API key has no Bitrix24 tokens configured
403	`SCOPE_DENIED`	The API key does not have the `im` scope
403	`WRITE_BLOCKED_READONLY_KEY`	The key is read-only: the portal may create a settings-preset binding during GET
422	`BITRIX_ERROR`	Bitrix24 returned an error; the portal code is in `error.b24Code`. `SETTINGS_ACCESS_DENIED` — a non-administrator requested another user's settings
502	`ME_ALIAS_RESOLUTION_FAILED`	`userId` was not passed, and the key owner could not be resolved
502	`BITRIX_UNAVAILABLE`	Bitrix24 is unavailable or returned a server error

Change a setting

PATCH /v1/chats/settings

Changes one general setting — the im.v2.Settings.General.update method. Without userId, changes the key owner's setting.

Parameters

The request body is a JSON object:

Field	Type	Required	Description
`name`	string	yes	Setting name — a key from the read response: a letter followed by letters, digits or `_`, up to 64 characters. Not `status`
`value`	string \| boolean	yes	The new value: a string (for example, `dark` for `enableDarkTheme`) or `true` / `false`
`userId`	number	no	ID of the user whose setting to change, a positive integer. Defaults to the key owner. Only a Bitrix24 administrator can change another user's settings

Any other body field and any query parameter are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal

curl -X PATCH "https://vibecode.bitrix24.com/v1/chats/settings" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "enableDarkTheme", "value": "dark"}'

curl — OAuth application

Terminal

curl -X PATCH "https://vibecode.bitrix24.com/v1/chats/settings" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "enableBigSmile", "value": false}'

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/settings', {
  method: 'PATCH',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'sendByEnter', value: false }),
})

const { success } = await res.json()
console.log('Accepted:', success)

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/settings', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'enableDarkTheme', value: 'dark' }),
})

const { success } = await res.json()
console.log('Accepted:', success)

Response fields

Field	Type	Description
`success`	boolean	Always `true` on success
`data`	boolean	`true` — Bitrix24 accepted the call. It does not mean the value changed: see "Known specifics"

Response example

JSON

{
  "success": true,
  "data": true
}

Error response example

400 — an attempt to change the status as a plain setting:

JSON

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "The status is set by PUT /v1/chats/settings/status: written as a plain setting it would not change the live status."
  }
}

Errors

HTTP	Code	Description
400	`INVALID_PARAMS`	`name` or `value` is missing or invalid, `name` equals `status`, `userId` is not a positive integer, or another body field or query parameter was passed
401	`TOKEN_MISSING`	The API key has no Bitrix24 tokens configured
403	`SCOPE_DENIED`	The API key does not have the `im` scope
403	`WRITE_BLOCKED_READONLY_KEY`	The key is read-only
422	`BITRIX_ERROR`	Bitrix24 returned an error; the portal code is in `error.b24Code`. `SETTINGS_ACCESS_DENIED` — a non-administrator is changing another user's setting
502	`ME_ALIAS_RESOLUTION_FAILED`	`userId` was not passed, and the key owner could not be resolved
502	`BITRIX_UNAVAILABLE`	Bitrix24 is unavailable or returned a server error

The full list of common API errors — Errors.

Known specifics

Bitrix24 answers true even when it changed nothing: it skips an unknown setting name, and for an enumerated setting it replaces a value outside the allowed set with the default (for example, enableDarkTheme accepts only auto, light, dark). To confirm the result, read the settings again.
true and false in value are sent to Bitrix24 as Y and N — that is how Bitrix24 accepts boolean settings.
Until the user changes any setting, they use the shared set of default settings. The first change creates a personal copy of the set for them.
Reading the settings of a user who is not yet bound to a settings set creates that binding — the values do not change.

General settings

Read settings

Parameters

Examples

curl — personal key

curl — OAuth application

JavaScript — personal key

JavaScript — OAuth application

Response fields

Response example

Error response example

Errors

Change a setting

Parameters

Examples

curl — personal key

curl — OAuth application

JavaScript — personal key

JavaScript — OAuth application

Response fields

Response example

Error response example

Errors

Known specifics

See also