Для AI-агентов: markdown этой страницы — /docs-content/chats/messages/search.md индекс документации — /llms.txt

Поиск сообщений в чате

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

Находит сообщения одного чата, в тексте которых встречается строка запроса. Ответ имеет форму ленты в режиме v2: найденные сообщения и коллекции к ним.

Искать чаты по названию — поиск чатов.

Параметры

Параметр Тип Обяз. По умолч. Описание
dialogId (path) string да — ID диалога: числовой ID пользователя для личных сообщений, chatXXX для групповых. Специальный алиас me — личный диалог текущего пользователя. chatXXX — поле id строки последних диалогов, ID пользователя — из списка пользователей
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 — личный ключ

Terminal 
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-приложение

Terminal 
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 загрузки чата
data.messages[].authorId number ID автора — профиль в data.users этого же ответа или по ID пользователя. 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 — Ошибки.

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

Поиск может сделать вас участником. Если чат разрешает автовступление, поиск добавляет текущего пользователя в участники — как загрузка чата. Ключу READONLY это чтение разрешено. Поиск сам не отмечает сообщения прочитанными. Права пользователя в Битрикс24 и скоуп im проверяются.

Совпадение — по подстроке. Запрос needle находит и probe-needle. Символы % и _ работают как шаблоны и не экранируются.

Находятся и системные сообщения. Сообщение о закреплении цитирует закреплённый текст, поэтому попадает в результаты вместе с оригиналом. Отличить его можно по authorId 0.

Дальше — лента. Чтобы открыть чат на найденном сообщении, возьмите сообщения вокруг сообщения.

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