## Поиск чатов по тексту

`GET /v1/chats/search`

Ищет чаты и диалоги по названию или тексту сообщений. Возвращает массив объектов чатов, соответствующих поисковому запросу.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `search` | string | да | Поисковая строка. При пустом значении возвращает результаты без фильтрации |

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/search?search=%D0%A1%D0%B4%D0%B5%D0%BB%D0%BA%D0%B0" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/search?search=%D0%A1%D0%B4%D0%B5%D0%BB%D0%BA%D0%B0" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const query = new URLSearchParams({ search: 'Сделка' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/chats/search?${query}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Найдено чатов:', data.length)
```

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

```javascript
const query = new URLSearchParams({ search: 'Сделка' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/chats/search?${query}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
```

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

| Поле | Тип | Описание |
|------|-----|---------|
| `data` | array | Массив найденных чатов |
| `data[].id` | number | Числовой ID чата |
| `data[].name` | string | Название чата |
| `data[].description` | string | Описание чата |
| `data[].type` | string | Тип чата: `chat`, `general`, `openlines`, `copilot`, `channel`, `crm`, `tasks` и другие |
| `data[].owner` | number | ID владельца чата |
| `data[].userCounter` | number | Количество участников |
| `data[].messageCount` | number | Общее количество сообщений |
| `data[].counter` | number | Количество непрочитанных сообщений |
| `data[].unreadId` | number | ID первого непрочитанного сообщения |
| `data[].lastMessageId` | number | ID последнего сообщения |
| `data[].entityType` | string | Тип связанной сущности (`CRM`, `TASKS`, `GENERAL` и другие) |
| `data[].entityId` | string | ID связанной сущности |
| `data[].entityLink` | object | Ссылка на связанную сущность |
| `data[].entityLink.type` | string | Тип ссылки |
| `data[].entityLink.url` | string | Относительный URL сущности на портале |
| `data[].entityLink.id` | string | ID сущности в строковом формате |
| `data[].dateCreate` | string | Дата создания чата (ISO 8601) |
| `data[].role` | string | Роль текущего пользователя: `owner`, `manager`, `member` |
| `data[].extranet` | boolean | Является ли чат экстранет-чатом |
| `data[].permissions` | object | Права участников по операциям |

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

```json
{
  "success": true,
  "data": [
    {
      "id": 456,
      "name": "Чат по сделке",
      "description": "Здесь обсуждаем детали сделки",
      "type": "crm",
      "owner": 1,
      "userCounter": 3,
      "messageCount": 9,
      "counter": 0,
      "unreadId": 0,
      "lastMessageId": 1450,
      "entityType": "CRM",
      "entityId": "DEAL|42",
      "entityLink": {
        "type": "CRM",
        "url": "/crm/deal/details/42/",
        "id": "DEAL|42"
      },
      "dateCreate": "2026-03-03T15:07:38+03:00",
      "role": "owner",
      "extranet": false,
      "permissions": {
        "manageUsersAdd": "member",
        "manageUsersDelete": "manager",
        "manageUi": "member",
        "manageSettings": "owner",
        "manageMessages": "member",
        "canPost": "member"
      }
    },
    {
      "id": 789,
      "name": "Обсуждение сделки №5",
      "description": null,
      "type": "chat",
      "owner": 12,
      "userCounter": 2,
      "messageCount": 4,
      "counter": 0,
      "unreadId": 0,
      "lastMessageId": 890,
      "entityType": "",
      "entityId": "",
      "entityLink": {
        "type": "",
        "url": "",
        "id": ""
      },
      "dateCreate": "2026-02-26T15:56:08+03:00",
      "role": "member",
      "extranet": false,
      "permissions": {
        "manageUsersAdd": "member",
        "manageUsersDelete": "manager",
        "manageUi": "member",
        "manageSettings": "owner",
        "manageMessages": "member",
        "canPost": "member"
      }
    }
  ]
}
```

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

403 — нет скоупа `im`:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'im' scope"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |
| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку (подробности в `message`) |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен или вернул ошибку сервера |

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

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

- Поиск выполняется по названию чата. Соответствие сообщениям зависит от возможностей портала и не гарантировано для всех типов чатов.
- Результаты не поддерживают пагинацию через `limit` и `offset`. При необходимости получить большее число результатов уточняйте поисковый запрос.
- Для поиска чата конкретной CRM-сущности используйте `GET /v1/chats/find` — он принимает `entityType` и `entityId` и возвращает точное совпадение.

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

- [Последние диалоги](/docs/chats/discovery/recent)
- [Найти чат CRM-сущности](/docs/chats/discovery/find)
- [Поиск чатов](/docs/chats/discovery)