# Notifications

Notifications for Bitrix24 users: sending personal and system notifications, reading the feed with its unread counter, searching the history, marking as read, answering a notification and pressing its button, deleting by ID, by tag, or all at once, notification groups, and delivery settings per channel. Notifications appear in the Notifications section of the Bitrix24 account.

**Scope:** `im` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`

[Documentation sections](#documentation-sections) | [Quick start](#quick-start) | [Full example](#full-example) | [Endpoint reference](#endpoint-reference) | [Error codes](#error-codes)

## Documentation sections

- [Endpoints](/docs/notifications/endpoints) — sending, the feed, the type dictionary, search, marking as read, answering a notification, pressing a button, deletion
- [Notification groups](/docs/notifications/groups) — reading, creating, renaming and deleting groups, adding and removing conditions
- [Notification settings](/docs/notifications/settings) — delivery channels per module event and the settings mode

## Quick start

Send a notification to a user by their `userId`:

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/notifications" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": 1, "message": "Deal #1024 moved to the Paid stage" }'
```

Response (HTTP 201):

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

## Full example

Send a notification, mark it as read, and delete it:

```javascript
const BASE = 'https://vibecode.bitrix24.com/v1'
const headers = {
  'X-Api-Key': 'YOUR_API_KEY',
  'Content-Type': 'application/json',
}

// 1. Send
const sendRes = await fetch(`${BASE}/notifications`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ userId: 1, message: 'Deal #1024 moved to the Paid stage' }),
})
const { data } = await sendRes.json()
const id = data.notificationId

// 2. Mark as read
await fetch(`${BASE}/notifications/read`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ id, onlyCurrent: true }),
})

// 3. Delete
const delRes = await fetch(`${BASE}/notifications/${id}`, {
  method: 'DELETE',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
console.log('Deleted:', delRes.status === 204)
```

## Endpoint reference

| Method | Path | Bitrix24 method | Description |
|-------|------|----------------|----------|
| POST | [/v1/notifications](/docs/notifications/send) | im.notify.personal.add | Send a notification to a user |
| GET | [/v1/notifications](/docs/notifications/list) | im.notify.get | Read the notification feed and the unread counter |
| GET | [/v1/notifications/schema](/docs/notifications/schema) | im.notify.schema.get | Read the notification type dictionary |
| GET | [/v1/notifications/search](/docs/notifications/search) | im.notify.history.search | Search the notification history by text, type, author and date |
| POST | [/v1/notifications/read](/docs/notifications/read) | im.notify.read; with `format=v2` — im.v2.Notify.read | Mark notifications as read |
| POST | [/v1/notifications/read-all](/docs/notifications/read-all) | im.v2.Notify.readAll | Mark all notifications as read except the listed ones |
| POST | [/v1/notifications/:id/answer](/docs/notifications/answer) | im.notify.answer | Answer a notification with text |
| POST | [/v1/notifications/:id/confirm](/docs/notifications/confirm) | im.notify.confirm | Click a button in a notification that requests a response |
| DELETE | [/v1/notifications/:id](/docs/notifications/delete) | im.notify.delete | Delete a notification by ID |
| DELETE | [/v1/notifications/by-tag/:tag](/docs/notifications/delete-by-tag) | im.notify.delete | Delete notifications by tag (OAuth application only) |
| DELETE | [/v1/notifications](/docs/notifications/delete-all) | im.v2.Notify.deleteAll | Delete all notifications of the key owner — irreversible |
| GET | [/v1/notifications/groups](/docs/notifications/groups/list) | im.v2.Notify.Group.list | Read notification groups |
| POST | [/v1/notifications/groups](/docs/notifications/groups/create) | im.v2.Notify.Group.add | Create a group with its first condition |
| PATCH | [/v1/notifications/groups/:groupId](/docs/notifications/groups/update) | im.v2.Notify.Group.update | Rename a group |
| DELETE | [/v1/notifications/groups/:groupId](/docs/notifications/groups/delete) | im.v2.Notify.Group.delete | Delete a group and all its conditions |
| POST | [/v1/notifications/groups/:groupId/conditions](/docs/notifications/groups/conditions-create) | im.v2.Notify.Condition.add | Add a condition to a group |
| DELETE | [/v1/notifications/groups/:groupId/conditions](/docs/notifications/groups/conditions-delete) | im.v2.Notify.Condition.delete | Remove a condition from a group |
| GET | [/v1/notifications/settings](/docs/notifications/settings/list) | im.v2.Settings.Notify.list | Get the notification delivery settings |
| PATCH | [/v1/notifications/settings](/docs/notifications/settings/update) | im.v2.Settings.Notify.update | Turn one delivery channel of an event on or off |
| PUT | [/v1/notifications/settings/scheme](/docs/notifications/settings/scheme) | im.v2.Settings.Notify.switchScheme | Switch the settings mode: advanced or simple |

Interactive method switcher with examples and response fields — [Endpoints](/docs/notifications/endpoints).

## Error codes

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `MISSING_PARAMS` | `userId` or `message` is missing when sending |
| 400 | `INVALID_PARAMS` | When deleting by ID, answering or pressing a button, `id` is not a positive integer. When answering, `text` is missing; when pressing a button, `value` is missing; when searching, `text` is shorter than 3 characters and no filter is passed. For marking with `format=v2`, marking all as read, deleting all, answering, pressing a button, searching, groups, conditions and settings, a query parameter or body field is unknown, duplicated or invalid. Checked before the Bitrix24 call |
| 400 | `INVALID_LIMIT` | `limit` is not an integer when reading the feed |
| 400 | `VALIDATION_ERROR` | The `lastId` and `lastType` cursor or the `convertText` value is invalid when reading the feed |
| 422 | `NOTIFICATION_NOT_DELIVERED` | The recipient is not on the portal or is deactivated |
| 404 | `ENTITY_NOT_FOUND` | The group does not exist or belongs to another user — the Bitrix24 code `GROUP_NOT_FOUND` is in the `error.b24Code` field |
| 404 | `ENTITY_NOT_FOUND` | `format=v2` marking only: the notifications were not found and the portal message says `Message is not found`; `error.b24Code` is `MESSAGE_NOT_FOUND` |
| 422 | `BITRIX_ERROR` | Bitrix24 refused the request; its code is in `error.b24Code`: `MESSAGE_NOT_FOUND` (for `format=v2`, the portal sent only the bare code without the `Message is not found` text), `SETTINGS_ACCESS_DENIED` (another user's settings without administrator rights), `400` (a repeated group condition), `NOTIFICATION_ACTION_FAILED` (the notification is absent, unavailable to the token owner, or does not accept an answer or a button press) |
| 403 | `BITRIX_ACCESS_DENIED` | Deletion by tag was requested with a personal key instead of an OAuth application key |
| 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 |
| 429 | `RATE_LIMITED` | Feed reading rate exceeded — up to 600 requests per minute per portal. The effective value is returned in the `x-ratelimit-limit` header |
| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 response could not be read |
| 502 | `ME_ALIAS_RESOLUTION_FAILED` | `userId` was not passed in a settings request, and the key owner could not be determined. Nothing was sent to Bitrix24 |

For the full list of common API errors, see [Errors](/docs/errors).

## See also

- [Send a notification](/docs/notifications/send)
- [Employees](/docs/entities/users)
- [Chats and messages](/docs/chats)
- [Errors](/docs/errors)