## Change a notification setting

`PATCH /v1/notifications/settings`

Turns one of an employee's notification delivery channels — `site`, `mail` or `push` — on or off for a single event of a Bitrix24 account module.

## 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`](/docs/notifications/settings/list) 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 |
| `userId` | number | no | ID of the employee whose setting to change — a positive integer. List: [`GET /v1/users`](/docs/entities/users/list). If omitted, the employee on whose behalf the call is made. Only a Bitrix24 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 }),
})
const { data } = await res.json()
```

### 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 }),
})
const { data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on success |
| `data` | boolean | Always `true`, including when the setting did not change |

## 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` was not passed, is empty or longer than 255 characters. The field is named in `message`. Checked before the Bitrix24 call |
| 400 | `INVALID_PARAMS` | `channel` is none of `site`, `mail` or `push` |
| 400 | `INVALID_PARAMS` | `enabled` was not passed or is neither `true` nor `false`. The string `"true"` and the number `1` are rejected |
| 400 | `INVALID_PARAMS` | `userId` is not a positive integer |
| 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` |
| 400 | `INVALID_PARAMS` | A query parameter was passed. The operation accepts no query parameters |
| 401 | `TOKEN_MISSING` | The key has no configured tokens |
| 403 | `SCOPE_DENIED` | The key lacks the `im` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |
| 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 |
| 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 |

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

## Known specifics

- 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 /v1/notifications/settings`](/docs/notifications/settings/list).

## See also

- [Get notification settings](/docs/notifications/settings/list)
- [Switch the notification settings mode](/docs/notifications/settings/scheme)
- [Notification settings](/docs/notifications/settings)