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

Unread counters

GET /v1/chats/counters

Returns the current user's unread message counters across all of their chats in one request — the v2 messenger method im.v2.Counter.get. Use it to show badges in the chat list without reading the messages themselves.

Parameters

There are no parameters. Any query parameter is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/counters" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

JavaScript — personal key

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

const { data } = await res.json()
const unread = data.userCounters.filter((c) => c.counter > 0 && !c.isMuted)
console.log('Chats with unread messages:', unread.length)

JavaScript — OAuth application

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

const { data } = await res.json()
const unread = data.userCounters.filter((c) => c.counter > 0 && !c.isMuted)
console.log('Chats with unread messages:', unread.length)

Response fields

Field Type Description
success boolean Always true on success
data.userCounters array Counters for chats that have unread messages or an "unread" mark
data.userCounters[].chatId number Chat ID — to open the chat, use chat loading with a dialogId of the form chat<chatId>
data.userCounters[].counter number Number of unread messages
data.userCounters[].parentChatId number ID of the parent chat for comment chats, otherwise 0; it opens the same way as chatId
data.userCounters[].isMuted boolean Notifications are turned off for the chat
data.userCounters[].isMarkedAsUnread boolean The chat was manually marked as unread
data.userCounters[].recentSections array Sections of the chat list the chat is counted in (default, chat, tasksTask and others)

Response example

JSON 
{
  "success": true,
  "data": {
    "userCounters": [
      {
        "chatId": 1945,
        "counter": 3,
        "parentChatId": 0,
        "isMuted": false,
        "isMarkedAsUnread": false,
        "recentSections": ["default"]
      }
    ]
  }
}

Error response example

400 — a query parameter was passed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Query parameter `unreadOnly` is not accepted by GET /v1/chats/counters. It takes no query parameters."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS A query parameter was passed — the endpoint takes none
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

The full list of general API errors — Errors.

Known specifics

  • Response keys are converted to camelCase; values are returned as is.

See also