## Search messages in a chat

`GET /v1/chats/:dialogId/messages/search`

Finds the messages of one chat whose text contains the query string — the v2 messenger method `im.v2.Chat.Message.search`. Newest first by default. The response has the shape of the [message history in the v2 mode](/docs/chats/messages/list): the messages found and the collections that go with them. The `me` alias as `dialogId` addresses the current user's personal dialog — see the [Chats overview](/docs/chats) for details.

To search chats by title, use [chat search](/docs/chats/discovery/search).

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|-----------|---------|
| `dialogId` (path) | string | yes | — | Dialog ID: numeric user ID for personal messages, `chatXXX` for group chats. The special `me` alias — the current user's personal dialog |
| `query` (query) | string | yes | — | Search string. At least 3 characters after trimming blanks |
| `lastId` (query) | number | no | — | Cursor: the smallest message `id` of the previous page, the largest with `order=asc`. The boundary itself is not included |
| `order` (query) | string | no | `desc` | `desc` — newest first, `asc` — oldest first |
| `limit` (query) | number | no | 50 | Messages per page, from 1 to 200: a value outside the range is clamped and echoed in `meta.requestedLimit` and `meta.appliedLimit` |

Any other parameter or a repeated parameter is rejected with `400 INVALID_PARAMS`.

## Examples

### curl — personal key

```bash
curl -X GET "https://vibecode.bitrix24.com/v1/chats/chat42/messages/search?query=mockup&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -X GET "https://vibecode.bitrix24.com/v1/chats/chat42/messages/search?query=mockup&limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/messages/search?query=mockup&limit=20', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
console.log('Found:', data.messages.map((m) => m.id), 'has more:', data.hasNextPage)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/messages/search?query=mockup&limit=20', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Found:', data.messages.map((m) => m.id), 'has more:', data.hasNextPage)
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.messages` | array | Messages found on the page |
| `data.messages[].id` | number | Message ID |
| `data.messages[].chatId` | number | Chat ID |
| `data.messages[].authorId` | number | Author ID. `0` — a system message |
| `data.messages[].date` | string | Sent date (ISO 8601) |
| `data.messages[].text` | string | Message text |
| `data.users` | array | Authors of the messages found |
| `data.usersShort` | array | Short user cards: `id`, `name`, `avatar`, `color`, `type` |
| `data.files` | array | Files of the messages found |
| `data.reactions` | array | Reactions to the messages found |
| `data.additionalMessages` | array | Messages referenced by the messages found: quotes and replies |
| `data.tariffRestrictions` | object | Plan restrictions on message history: `isHistoryLimitExceeded` |
| `data.hasNextPage` | boolean | There are more matching messages after this page |
| `meta.requestedLimit` | number | The `limit` passed, when it was outside the range from 1 to 200 |
| `meta.appliedLimit` | number | The `limit` value applied |

The response also carries `stickers`, `forwardSource` and `copilot` — collections of the v2 message history shared by all responses that return messages.

## Response example

```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 1002,
        "chatId": 42,
        "authorId": 7,
        "date": "2026-09-20T10:01:00+00:00",
        "text": "The mockup is ready for review",
        "params": {}
      }
    ],
    "users": [
      { "id": 7, "name": "Anna Smith", "firstName": "Anna", "lastName": "Smith", "avatar": "", "type": "user" }
    ],
    "usersShort": [
      { "id": 7, "name": "Anna Smith", "avatar": "", "color": "#df532d", "type": "user" }
    ],
    "files": [],
    "reactions": [],
    "stickers": [],
    "additionalMessages": [],
    "forwardSource": null,
    "copilot": null,
    "tariffRestrictions": { "isHistoryLimitExceeded": false },
    "hasNextPage": false
  }
}
```

## Error response example

400 — the query is shorter than three characters:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`query` is required: at least 3 characters after trimming blanks."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | No `query`, or it is shorter than 3 characters after trimming blanks; a parameter other than `query`, `lastId`, `order`, `limit`; a repeated parameter or an invalid value. Checked before any call to Bitrix24 |
| 404 | `ENTITY_NOT_FOUND` | Bitrix24 reported "not found"; the portal code is in `error.b24Code` |
| 422 | `BITRIX_ERROR` | Bitrix24 returned an error, for example `CHAT_NOT_FOUND`; the portal code is in `error.b24Code` |
| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |
| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |
| 502 | `ME_ALIAS_RESOLUTION_FAILED` | The `me` alias could not be resolved: Bitrix24 did not return the current user's ID |

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

## Known specifics

**Search may make you a member.** When the chat allows auto-join, search adds the current user as a member, as [loading a chat](/docs/chats/messages/load) does. A `READONLY` key may use this read operation; search does not mark messages read. The user's Bitrix24 access and the `im` scope still apply.

**A short query is rejected.** Bitrix24 does not apply the filter to a string shorter than three characters and would return the whole chat history instead of search results. Such a query is therefore rejected before any call to Bitrix24. Leading and trailing blanks do not count.

**Matching is by substring.** The query `needle` also finds `probe-needle`. Bitrix24 treats `%` and `_` as wildcards and does not escape them.

**System messages are found too.** The system message about a pin quotes the pinned text, so it appears in the results along with the original. You can tell it apart by `authorId` `0`.

**Continue in the message history.** To open the chat at a found message, use [messages around a message](/docs/chats/messages/context).

## See also

- [Read messages](/docs/chats/messages/list)
- [Messages around a message](/docs/chats/messages/context)
- [Chat search](/docs/chats/discovery/search)