Найти сообщения в чате im.dialog.messages.search

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: im

Кто может выполнять метод: участник чата или пользователь с доступом к открытому чату

Метод im.dialog.messages.search ищет сообщения в чате по тексту и дате.

Параметры метода

Обязательные параметры отмечены *

Название `тип`	Описание
CHAT_ID* `integer`	Идентификатор чата, в котором искать сообщения, — число без префикса `chat`. Его можно получить методом im.chat.get
SEARCH_MESSAGE `string`	Текст, который нужно найти в сообщениях. Метод ищет только по строке длиннее 2 символов. Если передать 1–2 символа, метод вернет сообщения чата без фильтра по тексту
DATE_FROM `datetime`	Начало периода поиска в формате ISO 8601 (RFC3339)
DATE_TO `datetime`	Конец периода поиска в формате ISO 8601 (RFC3339)
DATE `datetime`	Дата в формате ISO 8601 (RFC3339), за которую нужны сообщения. Если параметр передан, поиск выполняется в пределах суток от указанной даты
ORDER `object`	Сортировка. Доступно одно поле: `ID` — направление сортировки, значения `ASC` (по возрастанию) или `DESC` (по убыванию). Метод сортирует по дате создания сообщения, затем по `id` По умолчанию — `{"ID": "DESC"}`
LIMIT `integer`	Сколько сообщений вернуть. По умолчанию — `50`. Максимальное значение — `200`: большее метод уменьшает до `200`, а `0` и отрицательное заменяет на `50`
LAST_ID `integer`	Идентификатор последнего сообщения на предыдущей странице — поле `id` последнего элемента массива `messages`. Метод вернет сообщения, которые идут после него в порядке `ORDER`. Для первой страницы не передавайте

Как получить все результаты поиска

Запросите первую страницу без LAST_ID. Для следующей передайте в LAST_ID значение id последнего элемента массива messages: при сортировке DESC метод вернет сообщения с меньшим id, при ASC — с большим. Выборка закончена, когда пришло меньше сообщений, чем размер страницы — значение LIMIT с ограничениями из таблицы параметров.

Примеры кода

Как использовать примеры в документации

cURL (Webhook)

cURL (OAuth)

JS (TS)

JS (UMD)

Python

PHP

BX24.js

PHP CRest

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"CHAT_ID":3,"SEARCH_MESSAGE":"test","ORDER":{"ID":"DESC"},"LIMIT":20}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/im.dialog.messages.search

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"CHAT_ID":3,"SEARCH_MESSAGE":"test","ORDER":{"ID":"DESC"},"LIMIT":20,"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/im.dialog.messages.search

// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

// Shape of the payload returned in result (match the "response handling" section of the page)
type DialogMessagesSearchResult = {
  messages: Array<{
    id: number
    chatId: number
    chat_id: number
    authorId: number
    author_id: number
    date: ISODate
    text: string
    isSystem: boolean
    uuid: string | null
    forward: object | null
    params: Record<string, unknown> | unknown[]
    viewedByOthers: boolean
    unread: boolean
    viewed: boolean
    block: object | null
  }>
  users: unknown[]
  files: unknown[]
  additionalMessages: unknown[]
  copilot: object | null
  stickers: unknown[]
  reactions: unknown[]
  tariffRestrictions: { isHistoryLimitExceeded: boolean }
  usersShort: unknown[]
}

try {
  const response = await $b24.actions.v2.call.make<DialogMessagesSearchResult>({
    method: 'im.dialog.messages.search',
    params: {
      CHAT_ID: 3,
      SEARCH_MESSAGE: 'test',
      ORDER: { ID: 'DESC' },
      LIMIT: 20,
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Found messages:', result.messages.length, result.messages)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function searchDialogMessages() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'im.dialog.messages.search',
        params: {
          CHAT_ID: 3,
          SEARCH_MESSAGE: 'test',
          ORDER: { ID: 'DESC' },
          LIMIT: 20,
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Found messages:', result.messages.length, result.messages)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', searchDialogMessages)
</script>

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.im.dialog.messages.search(
        chat_id=3,
        search_message="test",
        order={
            "ID": "DESC",
        },
        limit=20,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")

try {
    $response = $b24Service
        ->core
        ->call(
            'im.dialog.messages.search',
            [
                'CHAT_ID' => 3,
                'SEARCH_MESSAGE' => 'test',
                'ORDER' => ['ID' => 'DESC'],
                'LIMIT' => 20,
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);
} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error: ' . $e->getMessage();
}

BX24.callMethod(
    'im.dialog.messages.search',
    {
        CHAT_ID: 3,
        SEARCH_MESSAGE: 'test',
        ORDER: { ID: 'DESC' },
        LIMIT: 20
    },
    function(result)
    {
        if (result.error())
        {
            console.error(result.error());
        }
        else
        {
            console.log(result.data());
        }
    }
);

require_once('crest.php');

$result = CRest::call(
    'im.dialog.messages.search',
    [
        'CHAT_ID' => 3,
        'SEARCH_MESSAGE' => 'test',
        'ORDER' => ['ID' => 'DESC'],
        'LIMIT' => 20,
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';

// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "im.dialog.messages.search", b24.Params{
	"CHAT_ID":        3,
	"SEARCH_MESSAGE": "test",
	"ORDER": b24.Params{
		"ID": "DESC",
	},
	"LIMIT": 20,
})
if err != nil {
	return fmt.Errorf("im.dialog.messages.search: %w", err)
}

// Форма ответа показана ниже на этой странице.
fmt.Printf("%s\n", res.Result)

Обработка ответа

HTTP-статус: 200

{
    "result": {
        "users": [
            {
                "id": 1,
                "active": true,
                "name": "Алекс",
                "firstName": "Алекс",
                "lastName": "",
                "workPosition": "",
                "color": "#df532d",
                "avatar": "https://cdn-ru.bitrix24.ru/path/avatar.jpg",
                "avatarHr": "https://cdn-ru.bitrix24.ru/path/avatar.jpg",
                "gender": "F",
                "birthday": "",
                "extranet": false,
                "network": false,
                "bot": false,
                "connector": false,
                "externalAuthId": "socservices",
                "internalAccount": true,
                "intranetUser": true,
                "status": "online",
                "idle": false,
                "lastActivityDate": "2026-02-13T14:27:33+03:00",
                "mobileLastDate": false,
                "desktopLastDate": false,
                "absent": false,
                "departments": [1, 107, 47, 3],
                "phones": {
                    "personal_mobile": "79998887766",
                    "inner_phone": "111"
                },
                "botData": null,
                "type": "user",
                "website": "",
                "email": "user@example.com"
            }
        ],
        "files": [],
        "additionalMessages": [],
        "copilot": null,
        "stickers": [],
        "reactions": [
            {
                "messageId": 33653,
                "reactionCounters": {
                    "like": 1
                },
                "reactionUsers": {
                    "like": [1]
                },
                "ownReactions": ["like"]
            }
        ],
        "tariffRestrictions": {
            "isHistoryLimitExceeded": false
        },
        "usersShort": [
            {
                "id": 1,
                "name": "Алекс",
                "avatar": "https://cdn-ru.bitrix24.ru/path/avatar.jpg",
                "color": "#df532d",
                "type": "user"
            }
        ],
        "messages": [
            {
                "id": 33653,
                "chatId": 3,
                "chat_id": 3,
                "authorId": 1,
                "author_id": 1,
                "date": "2026-02-13T14:28:00+03:00",
                "text": "test message",
                "isSystem": false,
                "uuid": "18533186-232b-4423-8438-64501da182f5",
                "forward": null,
                "params": {
                    "LIKE": [1]
                },
                "viewedByOthers": false,
                "block": null,
                "unread": false,
                "viewed": true
            }
        ]
    },
    "time": {
        "start": 1770982150,
        "finish": 1770982150.503861,
        "duration": 0.5038609504699707,
        "processing": 0,
        "date_start": "2026-02-13T14:29:10+03:00",
        "date_finish": "2026-02-13T14:29:10+03:00",
        "operating_reset_at": 1770982750,
        "operating": 0
    }
}

Возвращаемые данные

Название `тип`	Описание
result `object`	Найденные сообщения и связанные с ними данные (подробное описание)
time `time`	Информация о времени выполнения запроса

Объект result

Название `тип`	Описание
messages `array`	Массив найденных сообщений (подробное описание)
users `array`	Пользователи, связанные с найденными сообщениями (подробное описание)
files `array`	Файлы из найденных сообщений. Структура элемента — как у объекта file в ответе метода im.dialog.messages.get. Если файлов нет — пустой массив
additionalMessages `array`	Дополнительные сообщения, связанные с найденными, например пересылаемые или цитируемые (подробное описание)
copilot `object`	Данные BitrixGPT. Может быть `null`
stickers `array`	Стикеры, связанные с найденными сообщениями. Если стикеров нет — пустой массив
reactions `array`	Реакции на найденные сообщения (подробное описание)
tariffRestrictions `object`	Ограничения истории по тарифу. Флаг `isHistoryLimitExceeded` равен `true`, если тарифное ограничение истории убрало из выборки часть сообщений
usersShort `array`	Пользователи, которые поставили реакции: `id`, `name`, `avatar`, `color` — цвет аватара, `type` — тип пользователя. По этим данным можно показать имена и аватары для идентификаторов из `result.reactions[].reactionUsers`
commentInfo `array`	Данные о комментариях к найденным сообщениям. Заполняется для сообщений каналов

Если ничего не найдено, все массивы объекта result приходят пустыми.

Объект message

Название `тип`	Описание
id `integer`	Идентификатор сообщения
chatId `integer`	Идентификатор чата
chat_id `integer`	Идентификатор чата. То же, что `chatId`, в старом написании
authorId `integer`	Идентификатор автора сообщения
author_id `integer`	Идентификатор автора сообщения. То же, что `authorId`, в старом написании
date `datetime`	Дата и время создания сообщения
text `string`	Текст сообщения
isSystem `boolean`	Признак системного сообщения
uuid `string`	Внешний UUID сообщения. Может быть `null`
forward `object`	Информация о пересылке. `null`, если сообщение не переслано
params `object`	Параметры сообщения. Если параметров нет, приходит пустой массив `[]`
viewedByOthers `boolean`	Признак, что сообщение просмотрено другими участниками
unread `boolean`	Признак непрочитанного сообщения для текущего пользователя
viewed `boolean`	Признак, что сообщение просмотрено текущим пользователем
block `object`	Контентные блоки сообщения. `null`, если блоков нет

Объект user

Название `тип`	Описание
id `integer`	Идентификатор пользователя
active `boolean`	Пользователь активен
name `string`	Полное имя
firstName `string`	Имя
lastName `string`	Фамилия
workPosition `string`	Должность
color `string`	Цвет профиля в формате hex
avatar `string`	URL аватара
avatarHr `string`	URL аватара в высоком разрешении
gender `string`	Пол
birthday `string`	День рождения
extranet `boolean`	Признак экстранет-пользователя
intranetUser `boolean`	`true`, если пользователь — сотрудник: состоит в отделе компании и его учетная запись не внешняя
internalAccount `boolean`	`true`, если учетная запись не внешняя, например не принадлежит клиенту открытой линии
network `boolean`	Признак пользователя Bitrix24 Network
bot `boolean`	Признак бота
connector `boolean`	Признак пользователя-коннектора
externalAuthId `string`	Код внешней авторизации
status `string`	Статус пользователя
idle `datetime`	Дата в формате ISO 8601, если пользователь неактивен, иначе `false`
lastActivityDate `datetime`	Дата и время последней активности или `false`
mobileLastDate `datetime`	Последняя активность в мобильном приложении. Может быть `false`
desktopLastDate `datetime`	Последняя активность в десктоп-приложении. Может быть `false`
absent `datetime`	Дата в формате ISO 8601, если пользователь отсутствует, иначе `false`
departments `array`	Массив идентификаторов подразделений
phones `object`	Телефоны пользователя или `false`, если телефоны не заданы
botData `object`	Данные бота. Для обычного пользователя — `null`
type `string`	Тип пользователя
website `string`	Веб-сайт пользователя
email `string`	E-mail пользователя

Объект reactions

Название `тип`	Описание
messageId `integer`	Идентификатор сообщения
reactionCounters `object`	Количество реакций по типам: ключ — код реакции, например `like`, значение — число реакций
reactionUsers `object`	Кто поставил реакции: ключ — код реакции, значение — массив идентификаторов пользователей. Если реакций одного типа больше пяти, список может быть неполным. Имена и аватары этих пользователей — в `usersShort`
ownReactions `array`	Коды реакций, которые поставил текущий пользователь, например `["like"]`

Обработка ошибок

HTTP-статус: 400, 403

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "CHAT_ID can`t be empty"
}

Название `тип`	Описание
error `string`	Строковый код ошибки. Состоит из цифр, латинских букв и знака подчеркивания. Может прийти пустым — тогда причину показывает только `error_description`
error_description `string`	Текст ошибки для разработчика. Не показывайте его конечному пользователю без обработки

Возможные коды ошибок

Статус	Код	Описание	Значение
`400`	`CHAT_ID_EMPTY`	CHAT_ID can`t be empty	Параметр `CHAT_ID` не передан или его значение не число
`400`	`500`	`Incorrect date/time: <значение>`	Значение `DATE_FROM`, `DATE_TO` или `DATE` не распознано как дата
`400`	`ERROR_ARGUMENT`	Invalid order "UP"	В `ORDER` передано направление не `ASC` и не `DESC`. В тексте ошибки — переданное значение
`403`	`ACCESS_ERROR`	You do not have access to this chat	Нет доступа к указанному чату

Статусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус	Код Текст ошибки	Описание
`500`	`INTERNAL_SERVER_ERROR` Internal server error	Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	Превышен лимит на интенсивность запросов
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит
`401`	`NO_AUTH_FOUND` Wrong authorization data	В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука
`401`	`INVALID_REQUEST` Https required	Методы вызываются только по протоколу HTTPS
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24
`401`	`ACCESS_DENIED` REST is available only on commercial plans	REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом
`404`	`ERROR_METHOD_NOT_FOUND` Method not found!	Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на `provided by the access token`
`401`	`expired_token` The access token provided has expired	Срок действия access-токена истек
`401`	`user_access_error` The user does not have access to the application	Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям
`403`	`PORTAL_DELETED` Portal was deleted	Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение

Была ли статья полезна?

Получить сообщения чата

Отметить сообщения прочитанными

Найти сообщения в чате im.dialog.messages.search

Параметры методаПараметры метода

Как получить все результаты поискаКак получить все результаты поиска

Примеры кодаПримеры кода

Обработка ответаОбработка ответа

Возвращаемые данныеВозвращаемые данные

Объект resultОбъект result

Объект messageОбъект message

Объект userОбъект user

Объект reactionsОбъект reactions

Обработка ошибокОбработка ошибок

Возможные коды ошибокВозможные коды ошибок

Статусы и коды системных ошибокСтатусы и коды системных ошибок

Продолжите изучениеПродолжите изучение