[{"data":1,"prerenderedAt":10},["ShallowReactive",2],{"docs-chats\u002Fsettings":3,"docs-tabs-chats\u002Fsettings":6},{"content":4,"lastmod":5},"# Messenger settings\n\nReading and changing the user's general messenger settings and status — the same ones the user sees in the Bitrix24 messenger settings window.\n\n**Scope:** `im` | **Base URL:** `https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1` | **Authorization:** `X-Api-Key`\n\n## Operations\n\n- [Read settings](.\u002Fsettings\u002Flist.md) — `GET \u002Fv1\u002Fchats\u002Fsettings`\n- [Change a setting](.\u002Fsettings\u002Fupdate.md) — `PATCH \u002Fv1\u002Fchats\u002Fsettings`\n- [User status](.\u002Fsettings\u002Fstatus.md) — `PUT \u002Fv1\u002Fchats\u002Fsettings\u002Fstatus`\n\n## Whose settings\n\nWithout `userId`, the operations work with the key owner's settings: the platform resolves the owner and passes their ID to Bitrix24. Only a Bitrix24 administrator can read and change another user's settings — everyone else gets `422 BITRIX_ERROR` with the `SETTINGS_ACCESS_DENIED` code in `error.b24Code`.\n\nThe status is a setting too: the `status` field in the [read settings](.\u002Fsettings\u002Flist.md) response. It can be changed only through the separate [set status](.\u002Fsettings\u002Fstatus.md) operation, which updates both the setting and the status every messenger client sees.\n\n## See also\n\n- [Chats and messages](\u002Fdocs\u002Fchats)\n- [Service methods](\u002Fdocs\u002Fchats\u002Fservice)\n- [Notifications](\u002Fdocs\u002Fnotifications)\n","2026-10-06",{"settings\u002Flist.md":7,"settings\u002Fupdate.md":8,"settings\u002Fstatus.md":9},"## Read settings\n\n`GET \u002Fv1\u002Fchats\u002Fsettings`\n\nReturns the user's general messenger settings — sound, theme, sending with Enter, privacy, the notification scheme and more.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|----------|\n| `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. User list: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n\nAny other query parameter is rejected with `400 INVALID_PARAMS`.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings', {\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n})\n\nconst { data: settings } = await res.json()\nconsole.log('Theme:', settings.enableDarkTheme, 'Enter sends:', settings.sendByEnter)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { data: settings } = await res.json()\nconsole.log('Status:', settings.status)\n```\n\n## Response fields\n\n`data` is the settings object. Each key is a setting name, and each value is a string or a boolean. Bitrix24 defines the setting names, and the set depends on the messenger version. [Changing a setting](\u002Fdocs\u002Fchats\u002Fsettings\u002Fupdate) accepts the same names. The table describes the main settings. The response example shows the full set.\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | object | The settings: each key is a setting name, each value is a string or a boolean |\n| `data.status` | string | User status: `online`, `dnd` or `away`. Changed through [`PUT \u002Fv1\u002Fchats\u002Fsettings\u002Fstatus`](\u002Fdocs\u002Fchats\u002Fsettings\u002Fstatus) |\n| `data.enableSound` | boolean | Messenger sounds |\n| `data.enableBigSmile` | boolean | Large emoji in a message that consists of emoji only |\n| `data.enableDarkTheme` | string | Theme: `auto`, `light` or `dark` |\n| `data.sendByEnter` | boolean | `true` — a message is sent with Enter |\n| `data.chatAlignment` | string | Message alignment in a chat |\n| `data.pinnedChatSort` | string | Order of pinned chats |\n| `data.notifyScheme` | string | Notification scheme: `simple` or `expert` |\n| `data.privacySearch` | string | Who can find the user in search |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"status\": \"online\",\n    \"backgroundImage\": false,\n    \"bxdNotify\": false,\n    \"sshNotify\": true,\n    \"generalNotify\": false,\n    \"trackStatus\": \"\",\n    \"nativeNotify\": true,\n    \"openDesktopFromPanel\": false,\n    \"viewOffline\": true,\n    \"viewGroup\": true,\n    \"viewLastMessage\": true,\n    \"viewBirthday\": true,\n    \"viewCommonUsers\": true,\n    \"enableSound\": true,\n    \"enableBigSmile\": true,\n    \"defaultReaction\": \"like\",\n    \"enableDarkTheme\": \"dark\",\n    \"isCurrentThemeDark\": false,\n    \"enableRichLink\": true,\n    \"linesTabEnable\": true,\n    \"linesNewGroupEnable\": false,\n    \"sendByEnter\": true,\n    \"correctText\": false,\n    \"panelPositionHorizontal\": \"right\",\n    \"panelPositionVertical\": \"bottom\",\n    \"loadLastMessage\": true,\n    \"loadLastNotify\": true,\n    \"notifyAutoRead\": false,\n    \"notifyScheme\": \"expert\",\n    \"notifySchemeLevel\": \"important\",\n    \"notifySchemeSendSite\": false,\n    \"notifySchemeSendEmail\": false,\n    \"notifySchemeSendXmpp\": true,\n    \"notifySchemeSendPush\": false,\n    \"privacyMessage\": \"all\",\n    \"privacyChat\": \"all\",\n    \"privacyCall\": \"all\",\n    \"privacySearch\": \"all\",\n    \"privacyProfile\": \"all\",\n    \"callAcceptIncomingVideo\": \"AllowAll\",\n    \"backgroundImageId\": \"azure\",\n    \"chatAlignment\": \"left\",\n    \"pinnedChatSort\": \"byCost\"\n  }\n}\n```\n\n## Error response example\n\n400 — `userId` is not a positive integer:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"The query parameter `userId` must be a positive integer.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | `userId` is not a positive integer |\n| 400 | `INVALID_PARAMS` | A query parameter other than `userId` was passed |\n| 400 | `INVALID_PARAMS` | `userId` was passed more than once or with brackets, for example `userId[]=5` |\n| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |\n| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only. The request is rejected before any call to Bitrix24 |\n| 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 |\n| 502 | `ME_ALIAS_RESOLUTION_FAILED` | `userId` was not passed, and the key owner could not be resolved |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a server error |\n\nThe full list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- Reading the settings of a user who is not yet bound to a settings preset may create that binding without changing the values.\n- For a `userId` that does not exist in the Bitrix24 account, the response contains the default settings, without an error. To check that the user exists, use [`GET \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fget).\n\n## See also\n\n- [Change a setting](\u002Fdocs\u002Fchats\u002Fsettings\u002Fupdate)\n- [User status](\u002Fdocs\u002Fchats\u002Fsettings\u002Fstatus)\n- [Messenger settings](\u002Fdocs\u002Fchats\u002Fsettings)\n","## Change a setting\n\n`PATCH \u002Fv1\u002Fchats\u002Fsettings`\n\nChanges one of the user's general messenger settings — sound, theme, sending with Enter, privacy, the notification scheme and more.\n\n## Request fields (body)\n\nThe request body is a JSON object:\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `name` | string | yes | Setting name — a key from the [read settings](\u002Fdocs\u002Fchats\u002Fsettings\u002Flist) response: a letter followed by letters, digits or `_`, up to 64 characters. The value `status` is not accepted |\n| `value` | string \\| boolean | yes | The new value: a string or `true` \u002F `false`. Example string: `dark` for `enableDarkTheme` |\n| `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 \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n\nAny other body field and any query parameter are rejected with `400 INVALID_PARAMS`.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"name\": \"enableDarkTheme\", \"value\": \"dark\"}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"name\": \"enableDarkTheme\", \"value\": \"dark\"}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings', {\n  method: 'PATCH',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({ name: 'enableDarkTheme', value: 'dark' }),\n})\n\nconst { success } = await res.json()\nconsole.log('Accepted:', success)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ name: 'enableDarkTheme', value: 'dark' }),\n})\n\nconst { success } = await res.json()\nconsole.log('Accepted:', success)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | boolean | `true` — the call was accepted. It does not mean the value changed: see \"Known specifics\" |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": true\n}\n```\n\n## Error response example\n\n400 — an attempt to change the status as a plain setting:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"The status is set by PUT \u002Fv1\u002Fchats\u002Fsettings\u002Fstatus: written as a plain setting it would not change the live status.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | `name` is missing |\n| 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 |\n| 400 | `INVALID_PARAMS` | `name` equals `status` — the status is changed with [`PUT \u002Fv1\u002Fchats\u002Fsettings\u002Fstatus`](\u002Fdocs\u002Fchats\u002Fsettings\u002Fstatus) |\n| 400 | `INVALID_PARAMS` | `value` is missing |\n| 400 | `INVALID_PARAMS` | `value` is neither a string nor `true` \u002F `false` |\n| 400 | `INVALID_PARAMS` | `userId` is not a positive integer |\n| 400 | `INVALID_PARAMS` | The request body is not a JSON object |\n| 400 | `INVALID_PARAMS` | The body contains a field other than `name`, `value`, `userId` |\n| 400 | `INVALID_PARAMS` | A query parameter was passed — the method accepts none |\n| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |\n| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only |\n| 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 |\n| 502 | `ME_ALIAS_RESOLUTION_FAILED` | `userId` was not passed, and the key owner could not be resolved |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a server error |\n\nThe full list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- 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.\n- 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.\n\n## See also\n\n- [Read settings](\u002Fdocs\u002Fchats\u002Fsettings\u002Flist)\n- [User status](\u002Fdocs\u002Fchats\u002Fsettings\u002Fstatus)\n- [Messenger settings](\u002Fdocs\u002Fchats\u002Fsettings)\n","# User status\n\nSets the user's messenger status — \"online\", \"do not disturb\" or \"away\".\n\n## Set the status\n\n`PUT \u002Fv1\u002Fchats\u002Fsettings\u002Fstatus`\n\nUpdates both the `status` setting and the current status other users see.\n\n## Request fields (body)\n\nThe request body is a JSON object:\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `status` | string | yes | `online` — online, `dnd` — do not disturb, `away` — away |\n| `userId` | number | no | ID of the user whose status to set, a positive integer. Defaults to the key owner. Only a Bitrix24 administrator can change another user's status. User list: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n\nAny other body field and any query parameter are rejected with `400 INVALID_PARAMS`.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PUT \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings\u002Fstatus\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"status\": \"dnd\"}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PUT \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings\u002Fstatus\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"status\": \"dnd\"}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings\u002Fstatus', {\n  method: 'PUT',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({ status: 'dnd' }),\n})\n\nconst { data } = await res.json()\nconsole.log('Status set:', data)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fsettings\u002Fstatus', {\n  method: 'PUT',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ status: 'dnd' }),\n})\n\nconst { data } = await res.json()\nconsole.log('Status set:', data)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | boolean | `true` — the status is set |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": true\n}\n```\n\n## Error response example\n\n400 — the status is outside the allowed set:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"`status` must be `online`, `dnd` or `away`.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | `status` is missing |\n| 400 | `INVALID_PARAMS` | `status` is not `online`, `dnd` or `away` |\n| 400 | `INVALID_PARAMS` | `userId` is not a positive integer |\n| 400 | `INVALID_PARAMS` | The request body is not a JSON object |\n| 400 | `INVALID_PARAMS` | The body contains a field other than `status` and `userId` |\n| 400 | `INVALID_PARAMS` | A query parameter was passed — the method accepts none |\n| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |\n| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only |\n| 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 status |\n| 502 | `ME_ALIAS_RESOLUTION_FAILED` | `userId` was not passed, and the key owner could not be resolved |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a server error |\n\nThe full list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- The platform rejects `status` values other than `online`, `dnd` and `away` before calling Bitrix24: otherwise the `status` setting and the current status would diverge.\n- The status cannot be changed through [`PATCH \u002Fv1\u002Fchats\u002Fsettings`](\u002Fdocs\u002Fchats\u002Fsettings\u002Fupdate): that would change only the setting, while the status other users see would stay the same.\n- The current status is returned in the `status` field when you [read the settings](\u002Fdocs\u002Fchats\u002Fsettings\u002Flist).\n\n## See also\n\n- [Read settings](\u002Fdocs\u002Fchats\u002Fsettings\u002Flist)\n- [Change a setting](\u002Fdocs\u002Fchats\u002Fsettings\u002Fupdate)\n- [Messenger settings](\u002Fdocs\u002Fchats\u002Fsettings)\n",1794739552696]