For AI agents: markdown of this page — /docs-content-en/chats/management/read-section.md documentation index — /llms.txt

Read a list section

POST /v1/chats/recent/read

Marks as read every chat in one section of the current user's dialog list — for example, all task chats — and resets their unread counters. Other sections do not change.

Parameters

Query parameters are not accepted: any of them is rejected with 400 INVALID_PARAMS.

Request fields (body)

Field Type Required Description
section string yes Section code: a Latin letter, then letters, digits or _, up to 64 characters. The sections a chat is counted in arrive in the recentSections field of the unread counters
parentId integer no ID of the chat whose descendants are read, such as a channel's comments. A JSON integer, 1 or more. Without the field, the whole section is read

Other body fields are rejected with 400 INVALID_PARAMS.

Section codes in Bitrix24: default — the common list, chat — group chats, channel and openChannel — channels, collab — collabs, copilot — chats with the AI assistant, lines — Open Channels, tasksTask — task chats, calendar — calendar event chats.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/recent/read \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"section": "tasksTask"}'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/recent/read \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"section": "tasksTask"}'

JavaScript — personal key

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

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

JavaScript — OAuth application

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

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

Response fields

Field Type Description
success boolean Always true on success
data.result boolean true — the section is read. It also arrives when there was nothing to read

Response example

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

Error response example

400 — no section field:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`section` is required: the recent-list section to read, e.g. `default`."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS No section, no request body, section is not a section code, parentId is not a JSON integer or is less than 1, an extra body field or a query parameter. Checked before the Bitrix24 call
422 BITRIX_ERROR Bitrix24 returned an error; the Bitrix24 code is in error.b24Code
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY Read-only key: marking as read is a write, see access rights
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

Full list of common API errors — Errors.

Known specifics

An unknown section succeeds with no effect. A section code that does not exist in the Bitrix24 account returns true, and no counter changes. The response does not reveal a typo in section: check the code against the recentSections field of the unread counters.

The call cannot be undone. The "unread" marks and counters of the section's chats are reset at once. Reading is personal: it changes only the counters of the user on whose behalf the call is made.

See also