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

Update 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.

Get the state

GET /v1/chats/state

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

The v2 messenger method im.v2.UpdateState.getStateData.

Parameters

Parameter Type Required Description
siteId string no The Bitrix24 site to count the user counters for — two characters, usually 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
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 portal 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 call marks the user "online", just as any open messenger client does. This changes presence, so a read-only key gets 403 before any Bitrix24 call.
  • The keys of counters and eventParams are Bitrix24 codes and module IDs, and they arrive as is. The other keys are converted to camelCase.
  • Bitrix24 does not reject a siteId that does not exist.

See also