# Notifications

Send notifications to Bitrix24 users: personal and system notifications, marking as read, and deletion by id or tag. Notifications appear in the Notifications section of the Bitrix24 account.

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

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

## 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 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 |
| POST | [/v1/notifications/read](/docs/notifications/read) | im.notify.read | Mark notifications as read |
| DELETE | [/v1/notifications/:id](/docs/notifications/delete) | im.notify.delete | Delete a notification by identifier |
| DELETE | [/v1/notifications/by-tag/:tag](/docs/notifications/delete-by-tag) | im.notify.delete | Delete notifications by tag (OAuth application only) |

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 |
| 422 | `NOTIFICATION_NOT_DELIVERED` | The recipient is not in the portal or is deactivated |
| 403 | `BITRIX_ACCESS_DENIED` | Deletion by tag was called 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 |

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

## See also

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