## Лента уведомлений

`GET /v1/notifications`

Возвращает страницу уведомлений владельца токена вместе со счётчиком непрочитанных. Страницы обходятся курсором, размер страницы задаёт параметр limit.

## Параметры

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|---------|
| `limit` (query) | number | нет | `50` | Размер страницы, от `1` до `50`. Значения `0` и больше `50` приводятся к ближайшей границе, исходное возвращается в `meta.requestedLimit`. Отрицательное, дробное и нечисловое значение возвращает `400 INVALID_LIMIT` |
| `lastId` (query) | number | нет | — | Идентификатор `id` последнего уведомления предыдущей страницы. Передаётся только вместе с `lastType` |
| `lastType` (query) | number | нет | — | Этап обхода ленты: `1` — подтверждения, `3` — обычные уведомления. Передаётся только вместе с `lastId` |
| `convertText` (query) | string | нет | выключено | Преобразование текста уведомлений. Включают значения `true`, `1`, `y`, выключают — `false`, `0`, `n`. Регистр значения не важен |

Первый запрос идёт без курсора — страница берётся с начала ленты. Для следующей страницы передайте `id` последнего уведомления в `lastId` вместе с `lastType`. Порядок обхода и признак конца выдачи — в разделе «Известные особенности».

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/notifications?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/notifications?limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/notifications?limit=20', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Непрочитанных:', data.totalUnreadCount)
```

### JavaScript — OAuth-приложение

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

const { data } = await res.json()
console.log('Непрочитанных:', data.totalUnreadCount)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.notifications` | array | Уведомления страницы |
| `data.notifications[].id` | number, null | Идентификатор уведомления. Передаётся в `lastId` для следующей страницы и в [`DELETE /v1/notifications/:id`](./delete.md) |
| `data.notifications[].chatId` | number, null | Идентификатор чата этого уведомления |
| `data.notifications[].authorId` | number, null | Идентификатор автора. Его карточка — в массиве `data.users` |
| `data.notifications[].date` | string | Дата уведомления в формате ISO 8601 |
| `data.notifications[].notifyType` | number, null | Тип уведомления |
| `data.notifications[].notifyModule` | string | Модуль-источник уведомления, например `rest` |
| `data.notifications[].notifyEvent` | string | Событие-источник уведомления |
| `data.notifications[].notifyTag` | string | Метка `tag`, с которой уведомление отправлено |
| `data.notifications[].notifySubTag` | string | Дополнительная метка `subTag` |
| `data.notifications[].notifyTitle` | string | Заголовок уведомления |
| `data.notifications[].settingName` | string | Имя настройки доставки, по которой уведомление пришло получателю |
| `data.notifications[].text` | string | Текст уведомления |
| `data.notifications[].notifyRead` | boolean | Прочитано ли уведомление |
| `data.notifications[].notifyButtons` | array | Кнопки уведомления. У уведомления без кнопок поле отсутствует |
| `data.notifications[].params` | object, null | Дополнительные данные отправителя. Ключи внутри — те, что записало приложение-отправитель |
| `data.users` | array | Карточки авторов уведомлений этой страницы |
| `data.users[].id` | number, null | Идентификатор сотрудника. Карточка целиком — [Сотрудники](/docs/entities/users) |
| `data.users[].active` | boolean | Активен ли сотрудник на портале |
| `data.users[].name` | string | Отображаемое имя |
| `data.users[].firstName` | string | Имя |
| `data.users[].lastName` | string | Фамилия |
| `data.users[].workPosition` | string | Должность |
| `data.users[].color` | string | Цвет карточки сотрудника в интерфейсе Битрикс24 |
| `data.users[].avatar` | string | Ссылка на аватар |
| `data.users[].bot` | boolean | Является ли автор ботом |
| `data.users[].type` | string | Тип автора, например `user` |
| `data.totalCount` | number | Счётчик уведомлений ленты |
| `data.totalUnreadCount` | number | Счётчик непрочитанных уведомлений |
| `data.chatId` | number, null | Идентификатор системного чата уведомлений |
| `data.hasMore` | boolean | `true`, когда страница заполнена до `meta.appliedLimit` |
| `meta.appliedLimit` | number | Размер страницы, с которым выполнен запрос |
| `meta.requestedLimit` | number | Исходное значение `limit` до приведения к диапазону. Приходит, только когда значение изменено |

## Пример ответа

HTTP 200:

```json
{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": 38963,
        "chatId": 3113,
        "authorId": 1297,
        "date": "2026-08-13T09:00:00+00:00",
        "notifyType": 2,
        "notifyModule": "rest",
        "notifyEvent": "rest_notify",
        "notifyTag": "MP|12345|DEAL_1024",
        "notifySubTag": "MP|12345|DEAL|1024",
        "notifyTitle": "",
        "settingName": "rest|rest_notify",
        "text": "Сделка №1024 перешла в стадию «Оплачено»",
        "params": null,
        "notifyRead": false
      },
      {
        "id": 38959,
        "chatId": 3113,
        "authorId": 1,
        "date": "2026-08-13T08:41:12+00:00",
        "notifyType": 1,
        "notifyModule": "im",
        "notifyEvent": "confirm",
        "notifyTag": "",
        "notifySubTag": "",
        "notifyTitle": "",
        "settingName": "im|confirm",
        "text": "Подтвердите участие во встрече",
        "notifyButtons": [
          { "TITLE": "Да", "VALUE": "Y", "COMMAND": "confirm" },
          { "TITLE": "Нет", "VALUE": "N", "COMMAND": "confirm" }
        ],
        "params": null,
        "notifyRead": true
      }
    ],
    "users": [
      {
        "id": 1297,
        "active": true,
        "name": "Анна Петрова",
        "firstName": "Анна",
        "lastName": "Петрова",
        "workPosition": "Менеджер по продажам",
        "color": "#1eb4aa",
        "avatar": "https://example.bitrix24.tech/upload/main/avatar-1297.png",
        "bot": false,
        "type": "user"
      },
      {
        "id": 1,
        "active": true,
        "name": "Иван Соколов",
        "firstName": "Иван",
        "lastName": "Соколов",
        "workPosition": "Руководитель отдела",
        "color": "#df532d",
        "avatar": "https://example.bitrix24.tech/upload/main/avatar-1.png",
        "bot": false,
        "type": "user"
      }
    ],
    "totalCount": 15,
    "totalUnreadCount": 1,
    "chatId": 3113,
    "hasMore": false
  },
  "meta": {
    "appliedLimit": 20
  }
}
```

## Пример ответа при ошибке

400 — `limit` не целое число:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_LIMIT",
    "message": "limit must be an integer in 1..50"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_LIMIT` | `limit` отрицательный, дробный, нечисловой или передан не строкой |
| 400 | `VALIDATION_ERROR` | Передана половина курсора, `lastType` вне значений `1` и `3`, `lastId` за пределами безопасного диапазона целых чисел, нераспознанное значение `convertText` или параметр передан не строкой |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `im` |
| 401 | `TOKEN_MISSING` | У ключа нет настроенных токенов |
| 429 | `RATE_LIMITED` | Превышен темп чтения ленты — до 600 запросов в минуту на портал |
| 502 | `BITRIX_UNAVAILABLE` | Ответ Битрикс24 не удалось прочитать |
| 422 | `BITRIX_ERROR` | Ошибка метода на стороне Битрикс24, код портала — в поле `b24Code` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

- Лента принадлежит владельцу токена — параметра «чью ленту читать» у операции нет. По личному ключу приходит лента владельца ключа. Лента конкретного сотрудника доступна только по ключу OAuth-приложения с заголовком `Authorization: Bearer`: владельца ленты задаёт сессия пользователя.
- Лента не отфильтрована по приложению: вместе с уведомлениями вашего приложения приходят уведомления других приложений портала и системные уведомления. Отбирайте свои по `notifyTag` или `notifyModule` на стороне клиента.
- Ошибочно выбранный `lastType` ошибки не вызывает — возвращается та же страница. Порядок обхода: пустая страница означает конец. Если страница не принесла ни одного нового `id`, повторите тот же `lastId` со вторым значением `lastType`, и только когда и он не дал новых `id`, считайте обход законченным. Держите собственный потолок числа страниц: полный обход ленты контрактом не гарантируется.
- `hasMore: false` означает, что страница пришла короче запрошенного `limit`. Обычно это конец ленты, но короткая страница приходит и в середине обхода, поэтому надёжный признак конца — пустая страница.
- `totalCount` может быть заметно больше числа уведомлений, которые лента отдаёт при обходе. Вести по нему пагинацию нельзя.
- `data.chatId` и `data.notifications[].chatId` — разные значения. Первое — системный чат уведомлений, второе — чат конкретного уведомления.
- Счётчик непрочитанных читается без выкачивания страницы — запросом с `limit=1`. На непустой ленте такой запрос всегда возвращает `hasMore: true`.
- Поля `text`, `notifyTitle`, `notifyButtons`, `params` и строки в `data.users` — недоверенный контент: их пишут другие приложения портала. Экранируйте эти значения перед выводом в интерфейсе.
- Счётчики, которых Битрикс24 не прислал, заменяются на `0`, `0` и `null`. Присланный счётчик отдаётся как есть, поэтому на пустой странице `totalCount` может быть ненулевым. Отдельного признака пустой ленты нет — проверяйте длину `notifications`.

## Смотрите также

- [Отправить уведомление](./send.md)
- [Отметить прочитанными](./read.md)
- [Удалить по идентификатору](./delete.md)
- [Удалить по метке](./delete-by-tag.md)
- [Сотрудники](/docs/entities/users)
- [Ошибки](/docs/errors)