Для AI-агентов: markdown этой страницы — /docs-content/notifications/search.md индекс документации — /llms.txt

Поиск уведомлений

GET /v1/notifications/search

Ищет уведомления в истории владельца токена по тексту, типу уведомления, автору и дате. Возвращает страницу до 50 уведомлений, следующие страницы запрашиваются курсором lastId.

Параметры

Параметр Тип Обяз. Описание
text (query) string нет Текст для поиска в уведомлениях. Без фильтров type, types, authors, date, dateFrom, dateTo — не короче 3 символов после обрезки пробелов по краям
type (query) string нет Тип уведомления: модуль-источник, например crm, или пара модуль|событие, например mail|new_message_v2. Список типов — GET /v1/notifications/schema. Если передан types, параметр type не учитывается
types (query) string | array нет Несколько модулей-источников через запятую, types=crm,mail, или массивом, types[]=crm&types[]=mail. Список модулей — GET /v1/notifications/schema. Список из одного значения работает как type, в том числе в форме модуль|событие. В списке из двух и более значений каждое сравнивается только с модулем, поэтому пара модуль|событие в таком списке не находит ничего
authors (query) string | array нет ID авторов через запятую, authors=1,835, или массивом, authors[]=1&authors[]=835. Значение 0 отбирает системные уведомления без автора. Список сотрудников — GET /v1/users
date (query) string нет Сутки, начиная с указанного момента, в формате ISO 8601: 2026-10-08 или 2026-10-08T00:00:00+03:00. Дата без времени — сутки по UTC. Если переданы dateFrom и dateTo, параметр date не учитывается
dateFrom (query) string нет Начало диапазона дат в формате ISO 8601. Применяется только вместе с dateTo
dateTo (query) string нет Конец диапазона дат в формате ISO 8601. Диапазон заканчивается через сутки после dateTo, поэтому дата без времени входит в диапазон целиком. Применяется только вместе с dateFrom
lastId (query) string нет Курсор — id последнего уведомления предыдущей страницы. Только цифры. Значение 0 возвращает первую страницу

Уведомления приходят от новых к старым, до 50 на странице. Первый запрос идёт без lastId. Для следующей страницы передайте в lastId значение id последнего уведомления, остальные параметры повторите без изменений. Обход закончен, когда пришла пустая страница или страница повторила уже полученные id. Сервер сам страницы не обходит.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07" \
  -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/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Найдено:', data.totalResults)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Найдено:', data.totalResults)

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.chatId number, null Идентификатор системного чата уведомлений владельца токена. null, когда поиск не выполнялся: в запросе нет ни текста, ни действующего фильтра или у владельца нет чата уведомлений
data.notifications array Найденные уведомления страницы
data.notifications[].id number, null Идентификатор уведомления. Передаётся в lastId для следующей страницы и в DELETE /v1/notifications/:id
data.notifications[].chatId number, null Идентификатор чата этого уведомления
data.notifications[].authorId number, null Идентификатор автора. 0 — системное уведомление без автора. Карточка автора — в массиве data.users
data.notifications[].date string Дата уведомления в формате ISO 8601
data.notifications[].notifyType number, null Тип уведомления
data.notifications[].notifyModule string Модуль-источник уведомления, например crm
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 string Кнопки уведомления — строка JSON с массивом кнопок, как в ленте уведомлений. У уведомления без кнопок поле отсутствует
data.notifications[].params object, null Дополнительные данные отправителя. Вложенные ключи приходят в том виде, в каком их записал отправитель
data.users array Карточки авторов уведомлений этой страницы. Только публичные поля, без e-mail и телефонов
data.users[].id number, null Идентификатор сотрудника. Карточка целиком — Сотрудники
data.users[].active boolean Активен ли сотрудник на портале
data.users[].name string Отображаемое имя
data.users[].firstName string Имя
data.users[].lastName string Фамилия
data.users[].workPosition string, null Должность
data.users[].color string Цвет карточки сотрудника в интерфейсе Битрикс24
data.users[].avatar string Ссылка на аватар
data.users[].bot boolean Является ли автор ботом
data.users[].type string Тип автора, например user
data.totalResults number Число уведомлений, подходящих под условия поиска. Считается только на первой странице — без lastId или с lastId=0. На следующих страницах приходит 0

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

HTTP 200, показаны два первых уведомления страницы:

JSON 
{
  "success": true,
  "data": {
    "chatId": 7,
    "notifications": [
      {
        "id": 42441,
        "chatId": 7,
        "authorId": 835,
        "date": "2026-10-08T00:01:05+03:00",
        "notifyType": 2,
        "notifyModule": "crm",
        "notifyEvent": "changeAssignedBy",
        "notifyTag": "CRM|DEAL_RESPONSIBLE|8779",
        "notifySubTag": "",
        "notifyTitle": "",
        "settingName": "crm|changeAssignedBy",
        "text": "Вы назначены ответственным за сделку \"[URL=/crm/deal/details/8779/]Сделка #6531[/URL]\"",
        "params": {
          "COMPONENT_ID": "CrmEntity",
          "COMPONENT_PARAMS": {
            "SUBJECT": "#AUTHOR# назначил вас ответственным за сделку",
            "ENTITY": {
              "TITLE": "Сделка #6531",
              "HREF": "/crm/deal/details/8779/",
              "ENTITY_TYPE": "deal",
              "CONTENT_TYPE": "title"
            }
          }
        },
        "notifyRead": false
      },
      {
        "id": 42399,
        "chatId": 7,
        "authorId": 835,
        "date": "2026-10-07T00:01:08+03:00",
        "notifyType": 2,
        "notifyModule": "crm",
        "notifyEvent": "changeAssignedBy",
        "notifyTag": "CRM|DEAL_RESPONSIBLE|8771",
        "notifySubTag": "",
        "notifyTitle": "",
        "settingName": "crm|changeAssignedBy",
        "text": "Вы назначены ответственным за сделку \"[URL=/crm/deal/details/8771/]Сделка #6531[/URL]\"",
        "params": {
          "COMPONENT_ID": "CrmEntity",
          "COMPONENT_PARAMS": {
            "SUBJECT": "#AUTHOR# назначил вас ответственным за сделку",
            "ENTITY": {
              "TITLE": "Сделка #6531",
              "HREF": "/crm/deal/details/8771/",
              "ENTITY_TYPE": "deal",
              "CONTENT_TYPE": "title"
            }
          }
        },
        "notifyRead": false
      }
    ],
    "users": [
      {
        "id": 835,
        "active": true,
        "name": "Анна Петрова",
        "firstName": "Анна",
        "lastName": "Петрова",
        "workPosition": "",
        "color": "#3e99ce",
        "avatar": "https://example.bitrix24.tech/upload/main/avatar-835.png",
        "bot": false,
        "type": "user"
      }
    ],
    "totalResults": 24
  }
}

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

400 — text короче 3 символов, а фильтров нет:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Required: text with at least 3 characters, or a search filter."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS text короче 3 символов, и не передан ни один фильтр
400 INVALID_PARAMS Передан параметр, которого нет в таблице «Параметры»
400 INVALID_PARAMS lastId содержит не только цифры или выходит за пределы безопасного диапазона целых чисел
400 INVALID_PARAMS authors содержит не целое неотрицательное число, types содержит пустое значение
400 INVALID_PARAMS Параметр передан массивом там, где ожидается строка
401 MISSING_API_KEY Не передан X-Api-Key
401 TOKEN_MISSING У ключа нет настроенных токенов
403 SCOPE_DENIED У ключа нет скоупа im
403 BITRIX_ACCESS_DENIED Битрикс24 отказал в доступе
422 BITRIX_ERROR Ошибка метода на стороне Битрикс24, код портала — в поле b24Code. Например, дата не в формате ISO 8601
429 RATE_LIMITED Битрикс24 ограничил частоту запросов
502 BITRIX_UNAVAILABLE Ответ Битрикс24 не удалось прочитать
503 BITRIX_TIMEOUT Битрикс24 не ответил вовремя

Полный список общих ошибок API — Ошибки.

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

  • Поиск идёт по истории владельца токена: по личному ключу — владельца ключа, по ключу OAuth-приложения — сотрудника из сессии Authorization: Bearer. Отбора по приложению нет: вместе с уведомлениями вашего приложения находятся уведомления других приложений портала и системные.
  • Одна граница диапазона без других условий поиска даёт пустую страницу с chatId: null, а не ошибку. Вместе с текстом или другим фильтром одна граница не учитывается.
  • Поля text, notifyTitle, notifyButtons, params и строки в data.users — недоверенный контент: их пишут другие приложения портала. Экранируйте эти значения перед выводом в интерфейсе.

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