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
Fieldname Typestring Requiredyes DescriptionSetting 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
Fieldvalue Typestring | boolean Requiredyes DescriptionThe new value: a string or true / false. Example string: dark for enableDarkTheme
FielduserId Typenumber Requiredno DescriptionID 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeboolean Descriptiontrue — 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
HTTP400 CodeINVALID_PARAMS Descriptionname is missing
HTTP400 CodeINVALID_PARAMS Descriptionname 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
HTTP400 CodeINVALID_PARAMS Descriptionname equals status — the status is changed with PUT /v1/chats/settings/status
HTTP400 CodeINVALID_PARAMS Descriptionvalue is missing
HTTP400 CodeINVALID_PARAMS Descriptionvalue is neither a string nor true / false
HTTP400 CodeINVALID_PARAMS DescriptionuserId is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not a JSON object
HTTP400 CodeINVALID_PARAMS DescriptionThe body contains a field other than name, value, userId
HTTP400 CodeINVALID_PARAMS DescriptionA query parameter was passed — the method accepts none
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error; the portal code is in error.b24Code. SETTINGS_ACCESS_DENIED — a non-administrator is changing another user's setting
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionuserId was not passed, and the key owner could not be resolved
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 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