## Состояние обновлений

`GET /v1/chats/state`

Состояние мессенджера одним вызовом: ревизии, счётчики пользователя Битрикс24, счётчики чатов, последнее уведомление, в сети ли десктоп-приложение, время сервера.

Вызов отмечает пользователя «в сети» и меняет его статус присутствия на портале. Ключ только для чтения получает `403 WRITE_BLOCKED_READONLY_KEY` до обращения к Битрикс24.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `siteId` (query) | string | нет | Сайт Битрикс24, по которому считать счётчики пользователя, — два символа, например `s1`. По умолчанию — все сайты |

Другие параметры запроса отклоняются с `400 INVALID_PARAMS`.

## Примеры

### curl — личный ключ

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

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/state?siteId=s1" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/state', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Непрочитанных в мессенджере:', data.chatCounters.type.all)
console.log('Приглашений в календарь:', data.counters.calendar_invites)
```

### JavaScript — OAuth-приложение

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

const { data } = await res.json()
console.log('Ревизия:', data.revision, 'время сервера:', data.serverTime)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.revision` | number | Ревизия веб-клиента мессенджера |
| `data.mobileRevision` | number | Ревизия мобильного клиента |
| `data.counters` | object | Счётчики пользователя Битрикс24: ключ — код счётчика (`calendar_invites`, `crm_company_all`, `**` и другие), значение — число. Коды не переименовываются |
| `data.chatCounters` | object | Счётчики непрочитанного мессенджера: `type` — по видам чатов (`all`, `chat`, `dialog`, `collab`, `lines`, `copilot`, `notify` и другие), `chat` и `dialog` — по чатам (ключ — ID чата или собеседника), `chatMuted`, `chatUnread`, `dialogUnread` и другие — списки ID |
| `data.notifyLastId` | number \| null | ID последнего уведомления |
| `data.desktopStatus` | boolean | `true` — десктоп-приложение пользователя в сети |
| `data.serverTime` | number | Время сервера Битрикс24, Unix-время в секундах |
| `data.lastUpdate` | string | Время ответа в формате RFC 3339 |
| `data.eventParams` | object \| array | Данные модулей Битрикс24: ключ — ID модуля. Пустой массив, если модули ничего не передали |

## Пример ответа

```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": []
  }
}
```

## Пример ответа при ошибке

400 — некорректный `siteId`:

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `siteId` не два символа из букв, цифр и `_` или передан другой параметр запроса |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения. Вызов отмечает пользователя «в сети» |
| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку. Код портала — в `error.b24Code` |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен или вернул ошибку сервера |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

- Ключи `counters` и `eventParams` — коды Битрикс24 и ID модулей, они приходят как есть. Остальные ключи приводятся к camelCase.
- Несуществующий `siteId` не отклоняется.

## Смотрите также

- [Счётчики непрочитанного](/docs/chats/discovery/counters)
- [Служебные методы](/docs/chats/service)