# 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

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

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