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

Update state

GET /v1/chats/state

The messenger state in a single call: revisions, the Bitrix24 user counters, chat counters, the latest notification, whether the desktop app is online, and the server time.

The call marks the user online and changes their presence status in the Bitrix24 account. A read-only key gets 403 WRITE_BLOCKED_READONLY_KEY before any Bitrix24 call.

Parameters

Parameter Type Required Description
siteId (query) string no The Bitrix24 site to count the user counters for — two characters, for example s1. Defaults to all sites

Any other query parameter is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/state?siteId=s1" \
  -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/state', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Unread in the messenger:', data.chatCounters.type.all)
console.log('Calendar invitations:', data.counters.calendar_invites)

JavaScript — OAuth application

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

const { data } = await res.json()
console.log('Revision:', data.revision, 'server time:', data.serverTime)

Response fields

Field Type Description
success boolean Always true on success
data.revision number Revision of the messenger web client
data.mobileRevision number Revision of the mobile client
data.counters object Bitrix24 user counters: the key is the counter code (calendar_invites, crm_company_all, ** and others), the value is a number. The codes are not renamed
data.chatCounters object Messenger unread counters: type — by chat type (all, chat, dialog, collab, lines, copilot, notify and others), chat and dialog — by chat (the key is the chat ID or the other user's ID), chatMuted, chatUnread, dialogUnread and others — lists of IDs
data.notifyLastId number | null ID of the latest notification
data.desktopStatus boolean true — the user's desktop app is online
data.serverTime number Bitrix24 server time, Unix time in seconds
data.lastUpdate string Response time in RFC 3339 format
data.eventParams object | array Data from Bitrix24 modules: the key is the module ID. An empty array if the modules passed nothing

Response example

JSON 
{
  "success": true,
  "data": {
    "revision": 131,
    "mobileRevision": 29,
    "counters": { "**": 0, "calendar": 0, "calendar_invites": 0, "crm_company_all": 0 },
    "chatCounters": {
      "type": { "all": 5, "notify": 0, "chat": 3, "lines": 0, "dialog": 2, "copilot": 0, "collab": 0, "messenger": 5 },
      "chat": { "42": 3 },
      "dialog": { "7": 2 },
      "collab": [],
      "chatMuted": [],
      "chatUnread": [],
      "dialogUnread": [],
      "lines": []
    },
    "notifyLastId": null,
    "desktopStatus": false,
    "serverTime": 1790293283,
    "lastUpdate": "2026-09-24T23:41:23+00:00",
    "eventParams": []
  }
}

Error response example

400 — invalid siteId:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`siteId` must be a Bitrix24 site id: two letters, digits or `_` (e.g. `s1`)."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS siteId is not two characters made of letters, digits and _, or another query parameter was passed
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY Read-only key; the call marks the user online
422 BITRIX_ERROR Bitrix24 returned an error. The Bitrix24 code is in error.b24Code
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

The full list of common API errors — Errors.

Known specifics

  • The keys of counters and eventParams are Bitrix24 codes and module IDs, and they arrive as is. The other keys are converted to camelCase.
  • A siteId that does not exist is not rejected.

See also