## Общие чаты с пользователем

`GET /v1/chats/shared`

Возвращает чаты, в которых текущий пользователь состоит вместе с указанным сотрудником. Подходит для блока «Общие чаты» в карточке собеседника.

## Параметры

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|---------|
| `userId` (query) | integer | да | — | ID сотрудника, не меньше `1`. Список: [`GET /v1/users`](/docs/entities/users) |
| `limit` (query) | integer | нет | 50 | Чатов на странице, от 1 до 200. Меньшее значение поднимается до 1, большее срезается до 200, оба раза с эхом в `meta` |
| `offset` (query) | integer | нет | 0 | Сколько чатов пропустить, не меньше `0` |

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

**Обход.** Следующую страницу запрашивайте с `offset`, увеличенным на применённый `limit`. Конец списка — **пустая** страница, `data.chats` без элементов. Короткая страница концом не считается: страница бывает короче `limit`, хотя дальше есть ещё чаты.

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/shared?userId=4&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/shared?userId=4&limit=50" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const shared = []
for (let offset = 0; ; offset += 50) {
  const url = `https://vibecode.bitrix24.tech/v1/chats/shared?userId=4&limit=50&offset=${offset}`
  const res = await fetch(url, { headers: { 'X-Api-Key': 'YOUR_API_KEY' } })
  const { data } = await res.json()
  if (data.chats.length === 0) break
  shared.push(...data.chats)
}
```

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

```javascript
const shared = []
for (let offset = 0; ; offset += 50) {
  const url = `https://vibecode.bitrix24.tech/v1/chats/shared?userId=4&limit=50&offset=${offset}`
  const res = await fetch(url, {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  })
  const { data } = await res.json()
  if (data.chats.length === 0) break
  shared.push(...data.chats)
}
```

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

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.chats` | array | Общие чаты. Пустой массив — конец списка |
| `data.chats[].id` | number | ID чата |
| `data.chats[].dialogId` | string | ID диалога, `chatXXX` — для эндпоинтов сообщений |
| `data.chats[].name` | string | Название чата |
| `data.chats[].type` | string | Тип чата: `chat`, `general`, `openChannel`, `collab`, `calendar` и другие |
| `data.chats[].owner` | number | ID владельца чата |
| `data.chats[].role` | string | Роль текущего пользователя: `owner`, `manager`, `member` |
| `data.chats[].dateMessage` | string | Момент последнего сообщения чата |
| `meta.requestedLimit` | number | Переданный `limit`. Приходит вместе с `appliedLimit`, только когда значение вышло за диапазон от 1 до 200 |
| `meta.appliedLimit` | number | Применённый `limit` — только если он был приведён к границе |

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

Показаны основные поля:

```json
{
  "success": true,
  "data": {
    "chats": [
      {
        "id": 1,
        "dialogId": "chat1",
        "name": "Общий чат",
        "type": "general",
        "owner": 0,
        "role": "member",
        "dateMessage": "2026-09-24T18:02:11+00:00"
      },
      {
        "id": 264431,
        "dialogId": "chat264431",
        "name": "Подготовка релиза",
        "type": "chat",
        "owner": 1,
        "role": "owner",
        "dateMessage": "2026-09-24T21:10:22+00:00"
      }
    ]
  }
}
```

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

400 — нет `userId`:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`userId` is required: the user whose shared chats to list."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Нет `userId`, `userId` меньше `1`, `offset` меньше `0`, нечисловой `limit`, параметр вне `userId`, `limit`, `offset` или повтор параметра. Проверяется до обращения к Битрикс24 |
| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку, код портала — в `error.b24Code` |
| 403 | `BITRIX_ACCESS_DENIED` | Битрикс24 отказал в доступе |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен или вернул ошибку сервера |

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

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

**В ответе нет признака следующей страницы.** Обход идёт до пустой страницы, поэтому последний запрос обхода всегда возвращает пустой `data.chats`.

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

- [Последние диалоги](/docs/chats/discovery/recent)
- [Информация о диалоге](/docs/chats/discovery/get)
- [Поиск чатов](/docs/chats/discovery)