# Notification settings

Delivery channels for an employee's notifications about events in Bitrix24 account modules: reading the settings, turning a channel on or off for an event, and switching the settings mode.

## Get notification settings

`GET /v1/notifications/settings`

Shows, for each module of the Bitrix24 account, through which channels the employee receives notifications about each event: in the Bitrix24 web version and desktop app, by email, and in the mobile app.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `userId` (query) | number | no | ID of the employee whose settings to read. List: [`GET /v1/users`](/docs/entities/users). Without the parameter — the employee on whose behalf the call is made. Another employee's settings are available only to a Bitrix24 account administrator |

## Examples

### curl — personal key

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

### curl — OAuth application

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

const { data } = await res.json()
const im = data.find((m) => m.id === 'im')
console.log(im?.notices.map((n) => `${n.id}: site=${n.site} mail=${n.mail} push=${n.push}`))
```

### JavaScript — OAuth application

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

const { data } = await res.json()
console.log('Modules:', data.length)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | array | Modules of the Bitrix24 account with configurable notifications |
| `data[].id` | string | Module identifier. Matches `notifyModule` of a notification in the [notification feed](./list.md). This value is accepted by the `module` field when changing a setting and by the conditions of [notification groups](./group-conditions.md) |
| `data[].label` | string | Module name |
| `data[].notices` | array | Module events |
| `data[].notices[].id` | string | Event identifier. Matches `notifyEvent` of a notification in the notification feed |
| `data[].notices[].label` | string | Event name |
| `data[].notices[].site` | boolean | The "Web version and desktop app" channel. `true` — notifications about the event arrive through this channel |
| `data[].notices[].mail` | boolean | The "Email" channel |
| `data[].notices[].push` | boolean | The "Mobile devices (push notifications)" channel |
| `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` |

## Response example

Two modules are shown, each with some of its events. The set of modules and events depends on the Bitrix24 account.

HTTP 200:

```json
{
  "success": true,
  "data": [
    {
      "id": "im",
      "label": "Chats and calls",
      "notices": [
        {
          "id": "message",
          "label": "Direct chat message received",
          "site": true,
          "mail": true,
          "push": true,
          "disabled": ["site"]
        },
        {
          "id": "like",
          "label": "Reactions",
          "site": true,
          "mail": true,
          "push": false,
          "disabled": ["push"]
        }
      ]
    },
    {
      "id": "bizproc",
      "label": "Workflows",
      "notices": [
        {
          "id": "activity",
          "label": "Workflow notifications",
          "site": true,
          "mail": true,
          "push": true,
          "disabled": []
        },
        {
          "id": "wi_locked",
          "label": "Workflow aborted",
          "site": true,
          "mail": false,
          "push": false,
          "disabled": ["push"]
        }
      ]
    }
  ]
}
```

## 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 was passed twice, or another query parameter was passed. Checked before the Bitrix24 call |
| 422 | `BITRIX_ERROR` | Another employee's settings were requested without Bitrix24 administrator rights. The portal code `SETTINGS_ACCESS_DENIED` is in the `error.b24Code` field |
| 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 |
| 403 | `SCOPE_DENIED` | The key lacks the `im` scope |
| 401 | `TOKEN_MISSING` | The key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- 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.

## Change a notification setting

`PATCH /v1/notifications/settings`

Turns one delivery channel on or off for one module event.

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `module` | string | yes | Module identifier, 1 to 255 characters. List: `data[].id` in the `GET /v1/notifications/settings` response |
| `event` | string | yes | Identifier of an event of this module, 1 to 255 characters. List: `data[].notices[].id` in the same response |
| `channel` | string | yes | Delivery channel: `site`, `mail` or `push` |
| `enabled` | boolean | yes | `true` — turn the channel on, `false` — turn it off. Strings and numbers are rejected |
| `userId` | number | no | ID of the employee whose setting to change. List: [`GET /v1/users`](/docs/entities/users). Without the field — the employee on whose behalf the call is made. Only a Bitrix24 account administrator can change another employee's settings |

## Examples

### curl — personal key

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/notifications/settings" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "module": "bizproc", "event": "activity", "channel": "site", "enabled": false }'
```

### curl — OAuth application

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/notifications/settings" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "module": "bizproc", "event": "activity", "channel": "site", "enabled": false }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/settings', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ module: 'bizproc', event: 'activity', channel: 'site', enabled: false }),
})
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/settings', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ module: 'bizproc', event: 'activity', channel: 'site', enabled: false }),
})
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on success |
| `data` | boolean | Always `true`. The success indicator is the HTTP code `200`, not the value |

## Response example

HTTP 200:

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

## Error response example

400 — the channel is not one of the allowed values:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Body field `channel` must be one of: site, mail, push."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `module` or `event` is not a string of 1 to 255 characters, `channel` is not `site`, `mail` or `push`, `enabled` is neither `true` nor `false`, `userId` is not a positive integer, the body has an extra field, or a query parameter was passed. The field is named in `message`. Checked before the Bitrix24 call |
| 422 | `BITRIX_ERROR` | Changing another employee's settings without Bitrix24 administrator rights. The portal code `SETTINGS_ACCESS_DENIED` is in the `error.b24Code` field |
| 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 |
| 403 | `SCOPE_DENIED` | The key lacks the `im` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |
| 401 | `TOKEN_MISSING` | The key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- A `true` response does not confirm the change. The setting stays the same, and the response is still `true`, in two cases: the channel is listed in `disabled` for this event, or the Bitrix24 account has no module or event with this identifier. When the result matters, read the settings again with `GET /v1/notifications/settings`.

## Switch the settings mode

`PUT /v1/notifications/settings/scheme`

Switches the employee's notification settings mode: advanced, where each event is configured separately, or simple, where event settings are built from general channel switches.

> **Important:** switching to `simple` mode overwrites the settings of every event. Switching back to advanced `expert` mode does not restore the previous event settings. Before switching to simple mode, save the `GET /v1/notifications/settings` response — after the switch, event settings can be restored only with `PATCH /v1/notifications/settings` calls, one event channel per call.

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `scheme` | string | yes | Mode: `expert` — advanced, `simple` — simple. Case-sensitive: `SIMPLE` is rejected |
| `userId` | number | no | ID of the employee whose mode to switch. List: [`GET /v1/users`](/docs/entities/users). Without the field — the employee on whose behalf the call is made. Only a Bitrix24 account administrator can switch another employee's mode |

## Examples

### curl — personal key

```bash
curl -X PUT "https://vibecode.bitrix24.com/v1/notifications/settings/scheme" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheme": "expert" }'
```

### curl — OAuth application

```bash
curl -X PUT "https://vibecode.bitrix24.com/v1/notifications/settings/scheme" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scheme": "expert" }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/settings/scheme', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ scheme: 'expert' }),
})

const { data } = await res.json()
console.log('Modules:', data.length)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/settings/scheme', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ scheme: 'expert' }),
})

const { data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | array | The employee's settings after the switch — modules with events and channels in the same format as the [Get notification settings](#get-notification-settings) response |

## Response example

One module and some of its events are shown.

HTTP 200:

```json
{
  "success": true,
  "data": [
    {
      "id": "im",
      "label": "Chats and calls",
      "notices": [
        {
          "id": "message",
          "label": "Direct chat message received",
          "site": true,
          "mail": true,
          "push": true,
          "disabled": ["site"]
        },
        {
          "id": "like",
          "label": "Reactions",
          "site": true,
          "mail": true,
          "push": false,
          "disabled": ["push"]
        }
      ]
    }
  ]
}
```

## Error response example

400 — the mode is not one of the allowed values:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Body field `scheme` must be one of: expert, simple."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `scheme` is not `expert` or `simple`, `userId` is not a positive integer, the body has an extra field, or a query parameter was passed. The field is named in `message`. Checked before the Bitrix24 call |
| 422 | `BITRIX_ERROR` | Switching another employee's mode without Bitrix24 administrator rights. The portal code `SETTINGS_ACCESS_DENIED` is in the `error.b24Code` field |
| 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 |
| 403 | `SCOPE_DENIED` | The key lacks the `im` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |
| 401 | `TOKEN_MISSING` | The key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## See also

- [Notification groups](./groups.md)
- [Notification group conditions](./group-conditions.md)
- [Notification feed](./list.md)
- [Notification type dictionary](./schema.md)
- [Employees](/docs/entities/users)
- [Errors](/docs/errors)