[{"data":1,"prerenderedAt":10},["ShallowReactive",2],{"docs-notifications\u002Fsettings":3,"docs-tabs-notifications\u002Fsettings":6},{"content":4,"lastmod":5},"# Notification settings\n\nThe operations read and change the delivery channels for an employee's notifications about events in Bitrix24 modules, and switch the settings mode — advanced or simple.\n\n**Scope:** `im` | **Base URL:** `https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1` | **Authorization:** `X-Api-Key`\n\n## Operations\n\n- [Get notification settings](.\u002Fsettings\u002Flist.md) — `GET \u002Fv1\u002Fnotifications\u002Fsettings`\n- [Change a notification setting](.\u002Fsettings\u002Fupdate.md) — `PATCH \u002Fv1\u002Fnotifications\u002Fsettings`\n- [Switch the notification settings mode](.\u002Fsettings\u002Fscheme.md) — `PUT \u002Fv1\u002Fnotifications\u002Fsettings\u002Fscheme`\n\n## Whose settings\n\nWithout `userId`, the operations work with the settings of the employee on whose behalf the call is made. Only a Bitrix24 administrator can read and change another employee's settings. Everyone else gets `422 BITRIX_ERROR` with the `SETTINGS_ACCESS_DENIED` code in the `error.b24Code` field.\n\n## See also\n\n- [Notifications](\u002Fdocs\u002Fnotifications)\n- [Notification groups](\u002Fdocs\u002Fnotifications\u002Fgroups)\n- [Add a condition to a notification group](\u002Fdocs\u002Fnotifications\u002Fgroups\u002Fconditions-create)\n- [Notification feed](\u002Fdocs\u002Fnotifications\u002Flist)\n","2026-10-09",{"settings\u002Flist.md":7,"settings\u002Fupdate.md":8,"settings\u002Fscheme.md":9},"## Get notification settings\n\n`GET \u002Fv1\u002Fnotifications\u002Fsettings`\n\nReturns the channels through which an employee receives notifications about events in each module of the Bitrix24 account.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|----------|\n| `userId` (query) | number | no | ID of the employee whose settings to read — a positive integer. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist). If omitted, the settings of the employee on whose behalf the call is made are returned. Another employee's settings are available only to a Bitrix24 administrator |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fnotifications\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\u002Fnotifications\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\u002Fnotifications\u002Fsettings', {\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n})\n\nconst { data } = await res.json()\nconst im = data.find((m) => m.id === 'im')\nconsole.log(im?.notices.map((n) => `${n.id}: site=${n.site} mail=${n.mail} push=${n.push}`))\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fnotifications\u002Fsettings', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { data } = await res.json()\nconsole.log('Modules:', data.length)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | Always `true` on success |\n| `data` | array | Modules of the Bitrix24 account with configurable notifications |\n| `data[].id` | string | Module identifier. Matches `notifyModule` of a notification in the [feed](\u002Fdocs\u002Fnotifications\u002Flist). The same value is passed in the `module` field when [changing a setting](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Fupdate) and in [notification group conditions](\u002Fdocs\u002Fnotifications\u002Fgroups\u002Fconditions-create) |\n| `data[].label` | string | Module name |\n| `data[].notices` | array | Module events |\n| `data[].notices[].id` | string | Event identifier. Matches `notifyEvent` of a notification in the feed |\n| `data[].notices[].label` | string | Event name |\n| `data[].notices[].site` | boolean | The \"Web version and desktop app\" channel. `true` — notifications about the event arrive through this channel |\n| `data[].notices[].mail` | boolean | The \"Email\" channel |\n| `data[].notices[].push` | boolean | The \"Mobile devices (push notifications)\" channel |\n| `data[].notices[].disabled` | array | Event channels that cannot be changed: `site`, `mail`, `push`. The value of such a channel is set by the Bitrix24 account: `true` or `false` |\n\n## Response example\n\nTwo modules are shown, each with some of its events. The set of modules and events depends on the Bitrix24 account.\n\nHTTP 200:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": \"im\",\n      \"label\": \"Chats and calls\",\n      \"notices\": [\n        {\n          \"id\": \"message\",\n          \"label\": \"Direct chat messages\",\n          \"site\": true,\n          \"mail\": false,\n          \"push\": false,\n          \"disabled\": [\"site\"]\n        },\n        {\n          \"id\": \"like\",\n          \"label\": \"Reactions to your messages\",\n          \"site\": false,\n          \"mail\": false,\n          \"push\": false,\n          \"disabled\": [\"push\"]\n        }\n      ]\n    },\n    {\n      \"id\": \"bizproc\",\n      \"label\": \"Workflows\",\n      \"notices\": [\n        {\n          \"id\": \"activity\",\n          \"label\": \"Workflow notifications\",\n          \"site\": true,\n          \"mail\": false,\n          \"push\": false,\n          \"disabled\": []\n        },\n        {\n          \"id\": \"wi_locked\",\n          \"label\": \"Workflow aborted\",\n          \"site\": true,\n          \"mail\": false,\n          \"push\": false,\n          \"disabled\": [\"push\"]\n        }\n      ]\n    }\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. Checked before the Bitrix24 call |\n| 400 | `INVALID_PARAMS` | `userId` was passed more than once or with brackets, for example `userId[]=5` |\n| 400 | `INVALID_PARAMS` | A query parameter other than `userId` was passed. The accepted parameters are listed in `message` |\n| 401 | `TOKEN_MISSING` | The key has no configured tokens |\n| 403 | `SCOPE_DENIED` | The key lacks the `im` scope |\n| 422 | `BITRIX_ERROR` | `userId` points to another employee, and the employee on whose behalf the call is made has no Bitrix24 administrator rights. The portal code `SETTINGS_ACCESS_DENIED` is in the `error.b24Code` field |\n| 502 | `ME_ALIAS_RESOLUTION_FAILED` | `userId` was not passed, and the employee on whose behalf the call is made could not be determined. The settings were not requested |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- For an administrator, a non-existent `userId` does not cause an error: the response contains the default settings. A successful response does not confirm that an employee with this ID exists in the Bitrix24 account. To check the employee, use [`GET \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fget).\n\n## See also\n\n- [Change a notification setting](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Fupdate)\n- [Switch the notification settings mode](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Fscheme)\n- [Notification settings](\u002Fdocs\u002Fnotifications\u002Fsettings)\n- [Notification groups](\u002Fdocs\u002Fnotifications\u002Fgroups)\n- [Notification feed](\u002Fdocs\u002Fnotifications\u002Flist)\n","## Change a notification setting\n\n`PATCH \u002Fv1\u002Fnotifications\u002Fsettings`\n\nTurns one of an employee's notification delivery channels — `site`, `mail` or `push` — on or off for a single event of a Bitrix24 account module.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `module` | string | yes | Module identifier, 1 to 255 characters. List: `data[].id` in the [`GET \u002Fv1\u002Fnotifications\u002Fsettings`](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Flist) response |\n| `event` | string | yes | Identifier of an event of this module, 1 to 255 characters. List: `data[].notices[].id` in the same response |\n| `channel` | string | yes | Delivery channel: `site`, `mail` or `push` |\n| `enabled` | boolean | yes | `true` — turn the channel on, `false` — turn it off |\n| `userId` | number | no | ID of the employee whose setting to change — a positive integer. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist). If omitted, the employee on whose behalf the call is made. Only a Bitrix24 administrator can change another employee's settings |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fnotifications\u002Fsettings\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"module\": \"bizproc\", \"event\": \"activity\", \"channel\": \"site\", \"enabled\": false }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fnotifications\u002Fsettings\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"module\": \"bizproc\", \"event\": \"activity\", \"channel\": \"site\", \"enabled\": false }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fnotifications\u002Fsettings', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ module: 'bizproc', event: 'activity', channel: 'site', enabled: false }),\n})\nconst { data } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fnotifications\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({ module: 'bizproc', event: 'activity', channel: 'site', enabled: false }),\n})\nconst { data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on success |\n| `data` | boolean | Always `true`, including when the setting did not change |\n\n## Response example\n\nHTTP 200:\n\n```json\n{\n  \"success\": true,\n  \"data\": true\n}\n```\n\n## Error response example\n\n400 — the channel is not one of the allowed values:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"Body field `channel` must be one of: site, mail, push.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | `module` or `event` was not passed, is empty or longer than 255 characters. The field is named in `message`. Checked before the Bitrix24 call |\n| 400 | `INVALID_PARAMS` | `channel` is none of `site`, `mail` or `push` |\n| 400 | `INVALID_PARAMS` | `enabled` was not passed or is neither `true` nor `false`. The string `\"true\"` and the number `1` are rejected |\n| 400 | `INVALID_PARAMS` | `userId` is not a positive integer |\n| 400 | `INVALID_PARAMS` | The body contains a field that is not in the \"Request fields\" table, or the body is not a JSON object. The accepted fields are listed in `message` |\n| 400 | `INVALID_PARAMS` | A query parameter was passed. The operation accepts no query parameters |\n| 401 | `TOKEN_MISSING` | The key has no configured tokens |\n| 403 | `SCOPE_DENIED` | The key lacks the `im` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 422 | `BITRIX_ERROR` | `userId` points to another employee, and the employee on whose behalf the call is made has no Bitrix24 administrator rights. The portal code `SETTINGS_ACCESS_DENIED` is in the `error.b24Code` field |\n| 502 | `ME_ALIAS_RESOLUTION_FAILED` | `userId` was not passed, and the employee on whose behalf the call is made could not be determined. The setting was not changed |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- A `true` response does not confirm the change. In two cases the setting stays unchanged, yet the response is still `true`: the channel is in `disabled` for this event, or the Bitrix24 account has no module or event with this identifier. To check the result, read the settings again with [`GET \u002Fv1\u002Fnotifications\u002Fsettings`](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Flist).\n\n## See also\n\n- [Get notification settings](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Flist)\n- [Switch the notification settings mode](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Fscheme)\n- [Notification settings](\u002Fdocs\u002Fnotifications\u002Fsettings)\n","## Switch the notification settings mode\n\n`PUT \u002Fv1\u002Fnotifications\u002Fsettings\u002Fscheme`\n\nSwitches the employee's notification settings mode: advanced or simple. In advanced mode, each event is configured separately. In simple mode, event settings are built from general channel switches.\n\n> **Important:** switching to simple mode (`simple`) overwrites the settings of every event. Switching back to advanced mode (`expert`) does not restore the previous event settings. Before switching to simple mode, save the [`GET \u002Fv1\u002Fnotifications\u002Fsettings`](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Flist) response. After the switch, event settings can be restored only with [`PATCH \u002Fv1\u002Fnotifications\u002Fsettings`](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Fupdate) calls, one event channel per call.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `scheme` | string | yes | Mode: `expert` — advanced, `simple` — simple. Case-sensitive: `SIMPLE` is rejected |\n| `userId` | number | no | ID of the employee whose mode to switch — a positive integer. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist). If omitted, the employee on whose behalf the call is made. Only a Bitrix24 administrator can switch another employee's mode |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PUT \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fnotifications\u002Fsettings\u002Fscheme\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"scheme\": \"expert\" }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PUT \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fnotifications\u002Fsettings\u002Fscheme\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"scheme\": \"expert\" }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fnotifications\u002Fsettings\u002Fscheme', {\n  method: 'PUT',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ scheme: 'expert' }),\n})\n\nconst { data } = await res.json()\nconsole.log('Modules:', data.length)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fnotifications\u002Fsettings\u002Fscheme', {\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({ scheme: 'expert' }),\n})\n\nconst { data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | Always `true` on success |\n| `data` | array | The employee's settings after the switch — modules with events and channels in the same format as the [get settings](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Flist) response |\n\n## Response example\n\nOne module and some of its events are shown. The set of modules and events depends on the Bitrix24 account.\n\nHTTP 200:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": \"im\",\n      \"label\": \"Chats and calls\",\n      \"notices\": [\n        {\n          \"id\": \"message\",\n          \"label\": \"Direct chat messages\",\n          \"site\": true,\n          \"mail\": false,\n          \"push\": false,\n          \"disabled\": [\"site\"]\n        },\n        {\n          \"id\": \"like\",\n          \"label\": \"Reactions to your messages\",\n          \"site\": false,\n          \"mail\": false,\n          \"push\": false,\n          \"disabled\": [\"push\"]\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Error response example\n\n400 — the mode is not one of the allowed values:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"Body field `scheme` must be one of: expert, simple.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | `scheme` was not passed or is neither `expert` nor `simple`. Checked before the Bitrix24 call |\n| 400 | `INVALID_PARAMS` | `userId` is not a positive integer |\n| 400 | `INVALID_PARAMS` | The body contains a field other than `scheme` and `userId`, or the body is not a JSON object. The accepted fields are listed in `message` |\n| 400 | `INVALID_PARAMS` | A query parameter was passed. The operation accepts no query parameters |\n| 401 | `TOKEN_MISSING` | The key has no configured tokens |\n| 403 | `SCOPE_DENIED` | The key lacks the `im` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 422 | `BITRIX_ERROR` | `userId` points to another employee, and the employee on whose behalf the call is made has no Bitrix24 administrator rights. The portal code `SETTINGS_ACCESS_DENIED` is in the `error.b24Code` field |\n| 502 | `ME_ALIAS_RESOLUTION_FAILED` | `userId` was not passed, and the employee on whose behalf the call is made could not be determined. The mode was not changed |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Get notification settings](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Flist)\n- [Change a notification setting](\u002Fdocs\u002Fnotifications\u002Fsettings\u002Fupdate)\n- [Notification settings](\u002Fdocs\u002Fnotifications\u002Fsettings)\n",1794739593301]