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

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

POST /v1/chats/:dialogId/read

Отмечает сообщения диалога прочитанными — все или до указанного сообщения.

Параметры

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

Режим v2. format=v2 отмечает прочитанным весь чат. В data приходит { chatId, lastId, counter, viewedMessages }. Режим не принимает полей тела: messageId отклоняется с 400 INVALID_PARAMS — отметить прочитанными отдельные сообщения можно операцией POST /v1/chats/messages/read. Параметры строки запроса кроме format тоже отклоняются.

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

Поле Тип Обяз. Описание
messageId number нет Прочитать все сообщения до указанного включительно. Без параметра — прочитать все сообщения в диалоге. Нечисловое значение игнорируется, и тогда тоже прочитываются все сообщения. В режиме v2 отклоняется

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/chat42/read" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "messageId": 1002 }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/chat42/read" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "messageId": 1002 }'

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

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

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

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

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

const { success, data } = await res.json()

curl — режим v2

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/chat42/read?format=v2" \
  -H "X-Api-Key: YOUR_API_KEY"

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.dialogId string ID диалога из запроса
data.chatId number Числовой ID чата
data.lastId number ID последнего прочитанного сообщения
data.counter number Количество непрочитанных сообщений, оставшихся после операции
data.viewedMessages array Режим v2: ID сообщений, отмеченных этим вызовом

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

JSON 
{
  "success": true,
  "data": {
    "dialogId": "chat42",
    "chatId": 42,
    "lastId": 1002,
    "counter": 0
  }
}

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

404 — диалог не найден или нет доступа:

JSON 
{
  "success": false,
  "error": {
    "code": "DIALOG_NOT_FOUND_OR_NO_ACCESS",
    "message": "Dialog does not exist or you cannot access it."
  }
}

Ошибки

HTTP Код Описание
404 DIALOG_NOT_FOUND_OR_NO_ACCESS Диалог не существует или нет доступа к нему
400 INVALID_PARAMS Только режим v2: поле тела, в том числе messageId, или параметр строки запроса кроме format
422 BITRIX_ERROR Битрикс24 вернул ошибку (текст в поле message). Код портала — в error.b24Code
502 BITRIX_UNAVAILABLE Битрикс24 недоступен или вернул ошибку сервера
502 ME_ALIAS_RESOLUTION_FAILED Только режим v2: не удалось определить пользователя при использовании алиаса me
403 BITRIX_ACCESS_DENIED Только режим v2: чата нет или к нему нет доступа
403 SCOPE_DENIED Ключу не хватает скоупа im
403 WRITE_BLOCKED_READONLY_KEY Ключ в режиме «только чтение»
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24

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

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