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
ParametersiteId (query) Typestring Requiredno DescriptionThe 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.revision Typenumber DescriptionRevision of the messenger web client
Fielddata.mobileRevision Typenumber DescriptionRevision of the mobile client
Fielddata.counters Typeobject DescriptionBitrix24 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
Fielddata.chatCounters Typeobject DescriptionMessenger 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
Fielddata.notifyLastId Typenumber | null DescriptionID of the latest notification
Fielddata.desktopStatus Typeboolean Descriptiontrue — the user's desktop app is online
Fielddata.serverTime Typenumber DescriptionBitrix24 server time, Unix time in seconds
Fielddata.lastUpdate Typestring DescriptionResponse time in RFC 3339 format
Fielddata.eventParams Typeobject | array DescriptionData 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
HTTP400 CodeINVALID_PARAMS DescriptionsiteId is not two characters made of letters, digits and _, or another query parameter was passed
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionRead-only key; the call marks the user online
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error. The Bitrix24 code is in error.b24Code
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 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