## Shared chats with a user

`GET /v1/chats/shared`

Returns the chats in which both the current user and the given employee are members. Use it for a "Shared chats" block in the other person's profile card.

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|-----------|---------|
| `userId` (query) | integer | yes | — | Employee ID, `1` or more. List — [`GET /v1/users`](/docs/entities/users) |
| `limit` (query) | integer | no | 50 | Chats per page, 1 to 200. A smaller value is raised to 1 and a larger one is clamped to 200, both echoed in `meta` |
| `offset` (query) | integer | no | 0 | How many chats to skip, `0` or more |

Other parameters and repeated parameters are rejected with `400 INVALID_PARAMS`.

**Walk.** Request the next page with `offset` increased by the applied `limit`. The list ends at an **empty** page, `data.chats` with no items. A short page is not the end: a page can be shorter than `limit` while more chats follow.

## Examples

### curl — personal key

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

### curl — OAuth application

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

### JavaScript — personal key

```javascript
const shared = []
for (let offset = 0; ; offset += 50) {
  const url = `https://vibecode.bitrix24.com/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 application

```javascript
const shared = []
for (let offset = 0; ; offset += 50) {
  const url = `https://vibecode.bitrix24.com/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)
}
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.chats` | array | Shared chats. An empty array is the end of the list |
| `data.chats[].id` | number | Chat ID |
| `data.chats[].dialogId` | string | Dialog ID, `chatXXX`, for the message endpoints |
| `data.chats[].name` | string | Chat name |
| `data.chats[].type` | string | Chat type: `chat`, `general`, `openChannel`, `collab`, `calendar` and others |
| `data.chats[].owner` | number | ID of the chat owner |
| `data.chats[].role` | string | The current user's role: `owner`, `manager`, `member` |
| `data.chats[].dateMessage` | string | Instant of the chat's last message |
| `meta.requestedLimit` | number | The `limit` passed. It arrives together with `appliedLimit`, only when the value was outside the range of 1 to 200 |
| `meta.appliedLimit` | number | The `limit` applied |

## Response example

The main fields are shown:

```json
{
  "success": true,
  "data": {
    "chats": [
      {
        "id": 1,
        "dialogId": "chat1",
        "name": "General chat",
        "type": "general",
        "owner": 0,
        "role": "member",
        "dateMessage": "2026-09-24T18:02:11+00:00"
      },
      {
        "id": 264431,
        "dialogId": "chat264431",
        "name": "Release preparation",
        "type": "chat",
        "owner": 1,
        "role": "owner",
        "dateMessage": "2026-09-24T21:10:22+00:00"
      }
    ]
  }
}
```

## Error response example

400 — no `userId`:

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

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | No `userId`, `userId` less than `1`, `offset` less than `0`, a non-numeric `limit`, a parameter other than `userId`, `limit`, `offset`, or a repeated parameter. Checked before the Bitrix24 call |
| 422 | `BITRIX_ERROR` | Bitrix24 returned an error; the Bitrix24 code is in `error.b24Code` |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access |
| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |
| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a server error |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**The response has no next-page flag.** The walk runs until an empty page, so the last request of a walk always returns an empty `data.chats`.

## See also

- [Recent dialogs](/docs/chats/discovery/recent)
- [Dialog details](/docs/chats/discovery/get)
- [Chat discovery](/docs/chats/discovery)