## Chats by CRM card

`GET /v1/openlines/crm/chats`

Returns the Open Channel chats linked to a lead, deal, company or contact. Works on any Bitrix24 account and does not require the Open Channels 26.700.0 update.

The generic `filter` parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds `Warning: 299 - "filter is not supported on this endpoint and was ignored"`, and records unsupported-filter use in the server log.

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|-----------|----------|
| `crmEntityType` (query) | string | yes | — | CRM card type: `lead`, `deal`, `company` or `contact`. Case-insensitive |
| `crmEntityId` (query) | number | yes | — | CRM card ID, a positive integer. Lists: [`GET /v1/leads`](/docs/entities/leads/list), [`GET /v1/deals`](/docs/entities/deals/list), [`GET /v1/companies`](/docs/entities/companies/list), [`GET /v1/contacts`](/docs/entities/contacts/list) |
| `activeOnly` (query) | boolean \| string | no | `true` | `true`, `false`, `Y`, `N`, `1`, `0`. Without the parameter only open dialogs are returned; `false` adds closed ones |

Pass each parameter exactly once and under its flat name: a repeated parameter (`crmEntityId=1&crmEntityId=2`) and the bracket form (`crmEntityId[]=1`) are rejected with `400 INVALID_PARAMS`. Neither value is picked.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/openlines/crm/chats?crmEntityType=lead&crmEntityId=1001213&activeOnly=false" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/openlines/crm/chats?crmEntityType=lead&crmEntityId=1001213&activeOnly=false" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const params = new URLSearchParams({
  crmEntityType: 'lead',
  crmEntityId: '1001213',
  activeOnly: 'false',
})
const res = await fetch(`https://vibecode.bitrix24.com/v1/openlines/crm/chats?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)
for (const chat of data) {
  console.log(chat.chatId, chat.connectorTitle)
}
```

### JavaScript — OAuth application

```javascript
const params = new URLSearchParams({
  crmEntityType: 'lead',
  crmEntityId: '1001213',
  activeOnly: 'false',
})
const res = await fetch(`https://vibecode.bitrix24.com/v1/openlines/crm/chats?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
```

## Response fields

`data` is an array of chats. For a card with no Open Channel dialogs it is empty, and that is not an error. An empty array is also returned when no card with that `crmEntityId` exists.

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on a successful request |
| `data[].chatId` | number | Open Channel chat ID. Pass it as is to [`POST /v1/openlines/sessions/intercept`](/docs/openlines/sessions/intercept) and [`POST /v1/openlines/sessions/join`](/docs/openlines/sessions/join) — this is how the current operator joins the card's dialog |
| `data[].connectorId` | string \| null | ID of the channel the dialog came from |
| `data[].connectorTitle` | string \| null | Channel name for display in the interface |

## Response example

Request with `activeOnly=false` — the card's dialog is already closed:

```json
{
  "success": true,
  "data": [
    { "chatId": 4531, "connectorId": "telegrambot", "connectorTitle": "Telegram" }
  ]
}
```

The same request without `activeOnly`: the card has no open dialogs.

```json
{
  "success": true,
  "data": []
}
```

## Error response example

400 — card type outside the list:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "crmEntityType must be one of: lead, deal, company, contact (case-insensitive)."
  }
}
```

## Errors

| HTTP | Code | Description |
|:----:|-----|---------|
| 200 | `Warning: 299` | The filter is ignored by default; previous data is preserved and the warning is sent in the `Warning` header. |
| 400 (strict mode only) | `UNSUPPORTED_FILTER` | The server mode is disabled by default; until it is enabled, the endpoint preserves HTTP 200 and the previous data. |
| 400 | `MISSING_PARAMS` | A required parameter is missing: `crmEntityType` or `crmEntityId` |
| 400 | `INVALID_PARAMS` | A parameter value is invalid: `crmEntityType` outside the list, `crmEntityId` not a positive integer, `activeOnly` outside the set of allowed values. The same code is returned when a query parameter is passed twice or in bracket form. The check runs before Bitrix24 is called; `message` lists the allowed values |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key is not recognized |
| 401 | `TOKEN_MISSING` | A personal key has no access to the Bitrix24 portal, or an application key was sent without a session token in `Authorization` |
| 403 | `SCOPE_DENIED` | The key lacks the `imopenlines` scope |
| 403 | `BITRIX_ACCESS_DENIED` | The key's user has no access to the CRM object |
| 422 | `BITRIX_ERROR` | Bitrix24 refused; its code is returned in `error.b24Code` |
| 429 | `RATE_LIMITED` | The limit of 300 requests per minute per portal, not per key, was exceeded. The limit is divided across platform replicas, so the code can arrive before the 300th request. The effective value for the key is in the `x-ratelimit-limit` header, the remaining quota and reset time are in `x-ratelimit-remaining` and `x-ratelimit-reset`; they come with every response |
| 429 | `RATE_LIMITED` | Bitrix24 rejected the call under its request rate limit for the portal. The response carries a `Retry-After` header |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response of unexpected shape |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 accepted the call but did not respond in time |

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

## See also

- [Intercept a dialog](/docs/openlines/sessions/intercept)
- [Join a dialog](/docs/openlines/sessions/join)
- [Search sessions](/docs/openlines/sessions/search)
- [Dialog metadata](/docs/openlines/dialog)
- [Session history](/docs/openlines/history)
- [Send a message to the client](/docs/openlines/crm/messages)
- [CRM chat actions](/docs/openlines/crm)
- [Open Channels](/docs/openlines)