## Найти чат CRM-сущности

`GET /v1/chats/find`

Возвращает идентификатор чата, привязанного к указанной CRM-сущности. Когда чата для сущности нет, возвращает `data: null` — не ошибку.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `entityType` | string | да | Тип CRM-объекта. Пример: `CRM` |
| `entityId` | string | да | Составной идентификатор сущности. Формат: `<ТИП>\|<ID>`. Пример: `DEAL\|123` |

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/find?entityType=CRM&entityId=DEAL%7C123" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/find?entityType=CRM&entityId=DEAL%7C123" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const params = new URLSearchParams({ entityType: 'CRM', entityId: 'DEAL|123' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/chats/find?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
// data — объект { id } или null, если чат не создан
console.log('ID чата:', data?.id ?? 'не найден')
```

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

```javascript
const params = new URLSearchParams({ entityType: 'CRM', entityId: 'DEAL|123' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/chats/find?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
```

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

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | object \| null | Объект `{ id }` с идентификатором чата, или `null` если чат не создан |
| `data.id` | number | Идентификатор чата. Используется в `GET /v1/chats/:dialogId` |

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

Чат найден:

```json
{
  "success": true,
  "data": {
    "id": 456
  }
}
```

Чат для сущности не создан:

```json
{
  "success": true,
  "data": null
}
```

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

400 — не переданы обязательные параметры:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required query params: entityType (e.g. \"CRM\") and entityId (e.g. \"DEAL|123\")"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `MISSING_PARAMS` | Не передан `entityType` или `entityId` |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

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

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

- Параметр `entityId` передаётся в URL-кодировке: символ `|` кодируется как `%7C`. В JavaScript `URLSearchParams` выполняет кодирование автоматически.
- Перед обращением к полю `id` проверяйте `data !== null`: у сущности без чата ответ успешный, но `data` пустой.

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

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