Find Message in Chat im.dialog.messages.search

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

Scope: im

Who can execute the method: chat participant

The method im.dialog.messages.search performs a search for messages in the chat.

Method Parameters

Required parameters are marked with *

Name `type`	Description
CHAT_ID^* `integer`	Identifier of the chat in which the search is performed
SEARCH_MESSAGE `string`	Search string for the message text. Search for this parameter is performed for strings longer than 2 characters
DATE_FROM `datetime`	Start of the search period in ISO 8601 format (RFC3339)
DATE_TO `datetime`	End of the search period in ISO 8601 format (RFC3339)
DATE `datetime`	Search for messages on a specific date in ISO 8601 format (RFC3339). If the parameter is provided, the search is performed within 24 hours from the specified date
ORDER `object`	Sorting parameters. Supported field: `ID` — sort by message identifier, values `ASC` or `DESC` Default: `{"ID": "DESC"}`
LIMIT `integer`	Number of messages returned. Default value: `50`. Maximum value: `200`
LAST_ID `integer`	Identifier of the last message from the previous selection for pagination

Code Examples

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

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

try
        {
            const response = await $b24.callMethod(
                'im.dialog.messages.search',
                {
                    CHAT_ID: 3,
                    SEARCH_MESSAGE: 'test',
                    ORDER: { ID: 'DESC' },
                    LIMIT: 20
                }
            );
        
            const result = response.getData().result;
            console.log('Search result:', result);
        }
        catch (error)
        {
            console.error('Error:', 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>';

Response Handling

HTTP status: 200

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

Returned Data

Name `type`	Description
result `object`	Root element of the response
result.messages `array`	Array of found messages (detailed description)
result.users `array`	Users associated with the found messages (detailed description)
result.files `array`	Files from the found messages
result.additionalMessages `array`	Additional messages related to the found ones, such as forwarded or quoted (detailed description)
result.copilot `object`	BitrixGPT data, if present in the response. Can be `null`
result.stickers `array`	Stickers associated with the found messages
result.reactions `array`	Reactions to the found messages (detailed description)
result.tariffRestrictions `object`	Information about tariff restrictions on history. Contains the flag `isHistoryLimitExceeded` — an indication of exceeding the message history limit by the plan
result.usersShort `array`	Brief information about users who reacted. Used as a supplementary reference to `result.reactions.reactionUsers`, contains `id`, `name`, `avatar`
time `time`	Information about the request execution time

Message

Name `type`	Description
id `integer`	Identifier of the message
chat_id `integer`	Identifier of the chat
author_id `integer`	Identifier of the message author
date `datetime`	Date and time of message creation
text `string`	Text of the message
isSystem `boolean`	Indicator of a system message
uuid `string`	External UUID of the message. Can be `null`
forward `object`	Information about forwarding. Can be `null`
params `array`	Message parameters
viewedByOthers `boolean`	Indicator that the message has been viewed by other participants
unread `boolean`	Indicator of an unread message for the current user
viewed `boolean`	Indicator that the message has been viewed by the current user

User

Name `type`	Description
id `integer`	Identifier of the user
active `boolean`	User is active
name `string`	Full name
firstName `string`	First name
lastName `string`	Last name
workPosition `string`	Position
color `string`	Profile color in hex format
avatar `string`	Avatar URL
avatarHr `string`	High-resolution avatar URL
gender `string`	Gender
birthday `string`	Birthday
extranet `boolean`	Indicator of an extranet user
network `boolean`	Indicator of a Bitrix24 Network user
bot `boolean`	Indicator of a bot
connector `boolean`	Indicator of a connector user
externalAuthId `string`	External authorization code
status `string`	User status
idle `boolean`	Indicator of inactivity
lastActivityDate `datetime`	Date and time of last activity
mobileLastDate `datetime`	Last activity in the mobile app. Can be `false`
desktopLastDate `datetime`	Last activity in the desktop app. Can be `false`
absent `boolean`	Indicator of absence
departments `array`	Array of department identifiers
phones `object`	User's phones
botData `object`	Additional bot data. For a regular user `null`
type `string`	User type
website `string`	User's website
email `string`	User's e-mail

Reactions

Name `type`	Description
messageId `integer`	Identifier of the message
reactionCounters `object`	Count of reactions by each type
reactionUsers `object`	Users by types of reactions
ownReactions `array`	Reactions of the current user

Error Handling

HTTP status: 400, 403

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

Name `type`	Description
error `string`	String error code. It may consist of digits, Latin letters, and underscores
error_description `error_description`	Textual description of the error. The description is not intended to be shown to the end user in its raw form

Possible Error Codes

Code	Description	Value
`CHAT_ID_EMPTY`	CHAT_ID can't be empty	Required parameter `CHAT_ID` is not provided
`ACCESS_ERROR`	You do not have access to this chat	No access to the specified chat

Statuses and System Error Codes

HTTP Status: 20x, 40x, 50x

The errors described below may occur when calling any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	The current method is not permitted for calls using batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	The maximum length of parameters passed to the batch method has been exceeded
`401`	`NO_AUTH_FOUND` Wrong authorization data	Invalid access token or webhook code
`400`	`INVALID_REQUEST` Https required	The HTTPS protocol is required for method calls
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block; please contact Bitrix24 technical support to lift it
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	The REST API is only available on commercial plans
`403`	`INVALID_CREDENTIALS` Invalid request credentials	The user associated with the access token or webhook used to call the method lacks the necessary permissions
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	The manifest is not available
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires higher privileges than those provided by the webhook token
`401`	`expired_token` The access token provided has expired	The provided access token has expired
`403`	`user_access_error` The user does not have access to the application	The user does not have access to the application. This means that the application is installed, but the portal administrator has restricted access to this application to specific users only
`500`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open the public part of the site on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Get List of Recent Messages

Mark Messages as "Read"

Find Message in Chat im.dialog.messages.search

Method ParametersMethod Parameters

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

MessageMessage

UserUser

ReactionsReactions

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning