## 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

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

### curl — OAuth application

```bash
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](/docs/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

- [Unread counters](/docs/chats/discovery/counters)
- [Service methods](/docs/chats/service)