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

Отметить прочитанными

POST /v1/notifications/read

Отмечает уведомления получателя прочитанными или непрочитанными. По умолчанию отмечаются уведомление с указанным id и все с бо́льшим идентификатором.

Параметры

Параметр Тип Обяз. Описание
format (query) string нет v2 включает режим v2 — см. «Режим v2» ниже. Любое другое значение игнорируется, ответ прежний. Повтор format не отклоняется: из format=v1&format=v2 берётся последнее значение, то есть режим v2, а format=v2&format=v1 даёт прежний ответ. Форма format[]=v2 включает режим v2, если все её значения — v2

Поля запроса (body)

Поле Тип Обяз. Описание
id number нет Идентификатор уведомления из ответа POST /v1/notifications. Отмечаются это уведомление и все с бо́льшим id. Без поля id статусы не меняются
action string нет Y — отметить прочитанными, N — непрочитанными. По умолчанию Y
onlyCurrent boolean нет true отмечает только уведомление с указанным id. Иначе — все с идентификатором не меньше id
ids number[] нет Только режим v2, и там поле обязательно: от 1 до 100 положительных целых идентификаторов. Идентификатор — поле id уведомления в ленте или notificationId из ответа POST /v1/notifications

Режим v2. POST /v1/notifications/read?format=v2 отмечает прочитанными ровно уведомления из списка ids. Другие уведомления, в том числе с бо́льшим id, не затрагиваются, пометки «непрочитано» в этом режиме нет. Режим принимает только поле тела ids и параметр строки запроса format: поля id, action, onlyCurrent и любые другие отклоняются с 400 INVALID_PARAMS до обращения к Битрикс24. Вместо true в data приходят счётчик непрочитанных после вызова и список отмеченных уведомлений.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/notifications/read" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": 37421, "onlyCurrent": true }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/notifications/read" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": 37421, "onlyCurrent": true }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/notifications/read', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ id: 37421, onlyCurrent: true }),
})

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/notifications/read', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ id: 37421, onlyCurrent: true }),
})

curl — режим v2

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/notifications/read?format=v2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [38963] }'

Поля ответа

Обычный режим — без format=v2:

Поле Тип Описание
success boolean true при успешном выполнении
data boolean Всегда true. Признак успеха — HTTP-код 200, а не значение

Режим v2 — format=v2:

Поле Тип Описание
success boolean true при успешном выполнении
data object Результат отметки: счётчик непрочитанных и отмеченные уведомления
data.counter number Счётчик непрочитанных уведомлений после вызова
data.viewedMessages number[] Идентификаторы уведомлений, отмеченных прочитанными

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

HTTP 200:

JSON 
{
  "success": true,
  "data": true
}

Пример ответа — режим v2

JSON 
{
  "success": true,
  "data": {
    "counter": 0,
    "viewedMessages": [38963]
  }
}

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

403 — нет скоупа im:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'im' scope"
  }
}

Ошибки

HTTP Код Описание
400 FST_ERR_CTP_EMPTY_JSON_BODY Передан заголовок Content-Type: application/json, а тело пустое. Отправьте как минимум {}
400 INVALID_PARAMS Только режим v2: ids — не массив из 1–100 положительных целых идентификаторов, передано другое поле тела или параметр строки запроса, кроме format, либо тело не является объектом JSON. Поле названо в сообщении. Проверяется до обращения к Битрикс24
404 ENTITY_NOT_FOUND Только режим v2: уведомления из ids не найдены, а текст ошибки портала — Message is not found; код MESSAGE_NOT_FOUND — в error.b24Code
422 BITRIX_ERROR Только режим v2: уведомления из ids не найдены, но портал прислал лишь код MESSAGE_NOT_FOUND вместо текста; код — в error.b24Code
422 BITRIX_ERROR Только режим v2: Битрикс24 отклонил вызов по другой причине, код портала — в поле error.b24Code
403 SCOPE_DENIED У ключа нет скоупа im
403 WRITE_BLOCKED_READONLY_KEY Ключ в режиме «только чтение»
401 TOKEN_MISSING У ключа нет настроенных токенов

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

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

  • Передавайте тело всегда, как минимум {}. Заголовок Content-Type: application/json с пустым телом отклоняется на разборе запроса — 400 FST_ERR_CTP_EMPTY_JSON_BODY, до обработчика запрос не доходит.
  • Запрос с телом, но без поля id завершается успешно и статусы уведомлений не меняет. Передавайте id, чтобы действительно отметить уведомления.

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