## Search chats by text

`GET /v1/chats/search`

Searches chats and dialogs by title or message text. Returns an array of chat objects matching the search query.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `search` | string | yes | Search string. When empty, returns results without filtering |

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/chats/search?search=Deal" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/chats/search?search=Deal" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const query = new URLSearchParams({ search: 'Deal' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/chats/search?${query}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Chats found:', data.length)
```

### JavaScript — OAuth application

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

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `data` | array | Array of found chats |
| `data[].id` | number | Numeric chat ID |
| `data[].name` | string | Chat title |
| `data[].description` | string | Chat description |
| `data[].type` | string | Chat type: `chat`, `general`, `openlines`, `copilot`, `channel`, `crm`, `tasks`, and others |
| `data[].owner` | number | Chat owner ID |
| `data[].userCounter` | number | Number of members |
| `data[].messageCount` | number | Total number of messages |
| `data[].counter` | number | Number of unread messages |
| `data[].unreadId` | number | ID of the first unread message |
| `data[].lastMessageId` | number | ID of the last message |
| `data[].entityType` | string | Type of the linked entity (`CRM`, `TASKS`, `GENERAL`, and others) |
| `data[].entityId` | string | ID of the linked entity |
| `data[].entityLink` | object | Link to the linked entity |
| `data[].entityLink.type` | string | Link type |
| `data[].entityLink.url` | string | Relative URL of the entity in your Bitrix24 account |
| `data[].entityLink.id` | string | Entity ID in string format |
| `data[].dateCreate` | string | Chat creation date (ISO 8601) |
| `data[].role` | string | Role of the current user: `owner`, `manager`, `member` |
| `data[].extranet` | boolean | Whether the chat is an extranet chat |
| `data[].permissions` | object | Member permissions by operation |

## Response example

```json
{
  "success": true,
  "data": [
    {
      "id": 456,
      "name": "Deal chat",
      "description": "Here we discuss the deal details",
      "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+00:00",
      "role": "owner",
      "extranet": false,
      "permissions": {
        "manageUsersAdd": "member",
        "manageUsersDelete": "manager",
        "manageUi": "member",
        "manageSettings": "owner",
        "manageMessages": "member",
        "canPost": "member"
      }
    },
    {
      "id": 789,
      "name": "Discussion of deal No. 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+00:00",
      "role": "member",
      "extranet": false,
      "permissions": {
        "manageUsersAdd": "member",
        "manageUsersDelete": "manager",
        "manageUi": "member",
        "manageSettings": "owner",
        "manageMessages": "member",
        "canPost": "member"
      }
    }
  ]
}
```

## Error response example

403 — no `im` scope:

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

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |
| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |
| 422 | `BITRIX_ERROR` | Bitrix24 returned an error (details in `message`) |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a server error |

The full list of general API errors — [Errors](/docs/errors).

## Known specifics

- The search is performed by chat title. Matching messages depends on your Bitrix24 account's capabilities and is not guaranteed for all chat types.
- Results do not support pagination via `limit` and `offset`. If you need to get a larger number of results, refine the search query.
- To search for the chat of a specific CRM entity, use `GET /v1/chats/find` — it accepts `entityType` and `entityId` and returns an exact match.

## See also

- [Recent dialogs](/docs/chats/discovery/recent)
- [Find a CRM entity chat](/docs/chats/discovery/find)
- [Chat discovery](/docs/chats/discovery)