Unread mark

POST /v1/chats/:dialogId/unread

DELETE /v1/chats/:dialogId/unread

Sets and clears the "unread" mark on the chat's row in the recent dialog list — the mark the messenger shows after the "Mark as unread" command. The mark is independent of the unread message counter: it neither marks messages as read nor makes them unread.

• POST sets the mark — the v2 messenger method im.v2.Chat.unread.
• DELETE clears the mark — the method im.v2.Chat.read with onlyRecent: Y. The "read later" pointer is cleared together with the mark. Messages are not marked as read — use POST /v1/chats/:dialogId/read for that.

Both calls are writes: a read-only key gets 403 WRITE_BLOCKED_READONLY_KEY before any call to Bitrix24.

Parameters

There are no query parameters and no body fields. Any query parameter or body field is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

# Set the mark
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat123/unread" \
  -H "X-Api-Key: YOUR_API_KEY"

# Clear the mark
curl -X DELETE "https://vibecode.bitrix24.com/v1/chats/chat123/unread" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat123/unread" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat123/unread', {
  method: 'DELETE',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Unread messages:', data.counter)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat123/unread', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success } = await res.json()

Response fields

POST:

DELETE:

Response example

POST:

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

DELETE:

{
  "success": true,
  "data": {
    "chatId": 123,
    "lastId": 1002,
    "counter": 0,
    "viewedMessages": []
  }
}

Error response example

400 — a body field was sent:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Body field `unread` is not accepted by POST /v1/chats/:dialogId/unread. It takes no body fields."
  }
}

422 — the chat is not in the recent dialog list (DELETE):

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "READ_RECENT_ITEM_NOT_FOUND_ERROR",
    "b24Code": "READ_RECENT_ITEM_NOT_FOUND_ERROR"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

• POST does not report whether the mark was set. Bitrix24 returns { "result": true } regardless of the outcome: when the chat is not in the current user's recent dialog list — for example, the chat was hidden from the list — the mark is not set, but the response is the same. To check the result, read the unread field of the chat's row in the recent dialogs in the v2 mode or isMarkedAsUnread in the counters.
• DELETE works only on a list row. Bitrix24 refuses a chat outside the recent dialog list with the code READ_RECENT_ITEM_NOT_FOUND_ERROR. The row returns to the list when a new message arrives in the chat.
• The mark and the "read later" pointer are cleared by one call: they cannot be cleared separately.
• POST on a chat that is already marked changes nothing: the "read later" pointer, if set, stays where it was.

See also

• Read later
• Mark as read
• Unread counters
• Chat management