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

Change a setting

PATCH /v1/chats/settings

Changes one of the user's general messenger settings — sound, theme, sending with Enter, privacy, the notification scheme and more.

Request fields (body)

The request body is a JSON object:

Field Type Required Description
name string yes Setting name — a key from the read settings response: a letter followed by letters, digits or _, up to 64 characters. The value status is not accepted
value string | boolean yes The new value: a string or true / false. Example string: dark for enableDarkTheme
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. User list: GET /v1/users

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": "enableDarkTheme", "value": "dark"}'

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: 'enableDarkTheme', value: 'dark' }),
})

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 — the call was accepted. 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 is missing
400 INVALID_PARAMS name does not match the setting name format: it does not start with a letter, contains characters other than letters, digits and _, or is longer than 64 characters
400 INVALID_PARAMS name equals status — the status is changed with PUT /v1/chats/settings/status
400 INVALID_PARAMS value is missing
400 INVALID_PARAMS value is neither a string nor true / false
400 INVALID_PARAMS userId is not a positive integer
400 INVALID_PARAMS The request body is not a JSON object
400 INVALID_PARAMS The body contains a field other than name, value, userId
400 INVALID_PARAMS A query parameter was passed — the method accepts none
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

  • A true response does not confirm the change: an unknown setting name is skipped without an error, and for an enumerated setting a value outside the allowed set — for example, enableDarkTheme accepts only auto, light, dark — is replaced with the default. To confirm the result, read the settings again.
  • 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.

See also