## Поиск сообщений в чате `GET /v1/chats/:dialogId/messages/search` Находит сообщения одного чата, в тексте которых встречается строка запроса. Ответ имеет форму [ленты в режиме v2](/docs/chats/messages/list): найденные сообщения и коллекции к ним. Искать чаты по названию — [поиск чатов](/docs/chats/discovery/search). ## Параметры | Параметр | Тип | Обяз. | По умолч. | Описание | |----------|-----|:-----:|-----------|---------| | `dialogId` (path) | string | да | — | ID диалога: числовой ID пользователя для личных сообщений, `chatXXX` для групповых. Специальный алиас `me` — личный диалог текущего пользователя. `chatXXX` — поле `id` строки [последних диалогов](/docs/chats/discovery/recent), ID пользователя — из [списка пользователей](/docs/entities/users/list) | | `query` (query) | string | да | — | Строка поиска. После обрезки пробелов по краям — не короче 3 символов | | `lastId` (query) | number | нет | — | Курсор: наименьший `id` сообщения предыдущей страницы, с `order=asc` — наибольший. Сама граница в страницу не входит | | `order` (query) | string | нет | `desc` | `desc` — сначала новые, `asc` — сначала старые | | `limit` (query) | number | нет | 50 | Сообщений на странице, от 1 до 200: значение вне диапазона срезается, переданное и применённое значения — в `meta.requestedLimit` и `meta.appliedLimit` | Другие параметры и повторы отклоняются с `400 INVALID_PARAMS`. ## Примеры ### curl — личный ключ ```bash curl -X GET "https://vibecode.bitrix24.tech/v1/chats/chat42/messages/search?query=%D0%BC%D0%B0%D0%BA%D0%B5%D1%82&limit=20" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth-приложение ```bash curl -X GET "https://vibecode.bitrix24.tech/v1/chats/chat42/messages/search?query=%D0%BC%D0%B0%D0%BA%D0%B5%D1%82&limit=20" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/chat42/messages/search?query=%D0%BC%D0%B0%D0%BA%D0%B5%D1%82&limit=20', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_API_KEY', }, }) const { data } = await res.json() console.log('Найдено:', data.messages.map((m) => m.id), 'ещё есть:', data.hasNextPage) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/chat42/messages/search?query=%D0%BC%D0%B0%D0%BA%D0%B5%D1%82&limit=20', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { data } = await res.json() console.log('Найдено:', data.messages.map((m) => m.id), 'ещё есть:', data.hasNextPage) ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | Всегда `true` при успехе | | `data.messages` | array | Найденные сообщения страницы | | `data.messages[].id` | number | ID сообщения | | `data.messages[].chatId` | number | ID чата — совпадает с `data.chat.id` [загрузки чата](/docs/chats/messages/load) | | `data.messages[].authorId` | number | ID автора — профиль в `data.users` этого же ответа или по [ID пользователя](/docs/entities/users/get). `0` — системное сообщение | | `data.messages[].date` | string | Дата отправки (ISO 8601) | | `data.messages[].text` | string | Текст сообщения | | `data.users` | array | Авторы найденных сообщений | | `data.usersShort` | array | Краткие карточки пользователей: `id`, `name`, `avatar`, `color`, `type` | | `data.files` | array | Файлы найденных сообщений | | `data.reactions` | array | Реакции на найденные сообщения | | `data.additionalMessages` | array | Сообщения, на которые ссылаются найденные: цитаты и ответы | | `data.tariffRestrictions` | object | Ограничения тарифа на историю: `isHistoryLimitExceeded` | | `data.hasNextPage` | boolean | Есть ещё найденные сообщения за страницей | | `meta.requestedLimit` | number | Переданный `limit`, когда он вышел за диапазон от 1 до 200 | | `meta.appliedLimit` | number | Применённое значение `limit` — только если он был приведён к границе | Приходят также `stickers`, `forwardSource` и `copilot` — коллекции ленты v2, общие для ответов с сообщениями. ## Пример ответа ```json { "success": true, "data": { "messages": [ { "id": 1002, "chatId": 42, "authorId": 7, "date": "2026-09-20T10:01:00+03:00", "text": "Макет готов к ревью", "params": {} } ], "users": [ { "id": 7, "name": "Анна Смирнова", "firstName": "Анна", "lastName": "Смирнова", "avatar": "", "type": "user" } ], "usersShort": [ { "id": 7, "name": "Анна Смирнова", "avatar": "", "color": "#df532d", "type": "user" } ], "files": [], "reactions": [], "stickers": [], "additionalMessages": [], "forwardSource": null, "copilot": null, "tariffRestrictions": { "isHistoryLimitExceeded": false }, "hasNextPage": false } } ``` ## Пример ответа при ошибке 400 — запрос короче трёх символов: ```json { "success": false, "error": { "code": "INVALID_PARAMS", "message": "`query` is required: at least 3 characters after trimming blanks." } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `INVALID_PARAMS` | Нет `query` или после обрезки пробелов он короче 3 символов. Параметр кроме `query`, `lastId`, `order`, `limit`. Повтор параметра или некорректное значение. Проверяется до обращения к Битрикс24 | | 404 | `ENTITY_NOT_FOUND` | Битрикс24 вернул «не найдено». Код портала — в `error.b24Code` | | 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку, например `CHAT_NOT_FOUND`. Код портала — в `error.b24Code` | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` | | 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 | | 502 | `ME_ALIAS_RESOLUTION_FAILED` | Алиас `me` не удалось разрешить: Битрикс24 не вернул ID текущего пользователя | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности **Поиск может сделать вас участником.** Если чат разрешает автовступление, поиск добавляет текущего пользователя в участники — как [загрузка чата](/docs/chats/messages/load). Ключу `READONLY` это чтение разрешено. Поиск сам не отмечает сообщения прочитанными. Права пользователя в Битрикс24 и скоуп `im` проверяются. **Совпадение — по подстроке.** Запрос `needle` находит и `probe-needle`. Символы `%` и `_` работают как шаблоны и не экранируются. **Находятся и системные сообщения.** Сообщение о закреплении цитирует закреплённый текст, поэтому попадает в результаты вместе с оригиналом. Отличить его можно по `authorId` `0`. **Дальше — лента.** Чтобы открыть чат на найденном сообщении, возьмите [сообщения вокруг сообщения](/docs/chats/messages/context). ## Смотрите также - [Чтение сообщений](/docs/chats/messages/list) - [Сообщения вокруг сообщения](/docs/chats/messages/context) - [Поиск чатов по тексту](/docs/chats/discovery/search)