Get the List of Recent Messages im.dialog.messages.get

Scope: im

Who can execute the method: chat participant

The method im.dialog.messages.get retrieves messages from the specified dialog, including system messages. It does not support standard pagination due to the potential large volume of data.

Messages can only be retrieved without participating in the chat for Open Line chats via the method imopenlines.session.history.get.

Method Parameters

Required parameters are marked with *

Name `type`	Description
DIALOG_ID* `string`	Identifier of the chat in the format: `chatXXX` — chat `sgXXX` — group or project chat `XXX` — user identifier for personal chat The chat identifier can be obtained using the method im.chat.get. The user identifier can be obtained using the methods user.get and user.search
LAST_ID `integer`	Identifier of the message older than which messages need to be loaded. The method will return messages with identifiers less than the specified one.
FIRST_ID `integer`	Identifier of the message newer than which messages need to be loaded. The method will return messages with identifiers greater than the specified one. To load the very first messages of the dialog — pass `FIRST_ID` with the value `0`.
LIMIT `integer`	Limit on the number of messages in the response. If `LAST_ID` and `FIRST_ID` are not provided, the method will return the last N messages of the dialog specified in `LIMIT`. Default is `20`. Maximum value is `50`.

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 '{"DIALOG_ID":"chat1489","FIRST_ID":84869,"LIMIT":10}' \
          https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/im.dialog.messages.get

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"DIALOG_ID":"chat1489","FIRST_ID":84869,"LIMIT":10,"auth":"**put_access_token_here**"}' \
          https://**put_your_bitrix24_address**/rest/im.dialog.messages.get

try
        {
            const response = await $b24.callMethod(
                'im.dialog.messages.get',
                {
                    DIALOG_ID: 'chat1489',
                    FIRST_ID: 84869,
                    LIMIT: 10
                }
            );
        
            console.log(response.getData().result);
        }
        catch (error)
        {
            console.error(error);
        }

try {
            $response = $b24Service->core->call(
                'im.dialog.messages.get',
                [
                    'DIALOG_ID' => 'chat1489',
                    'FIRST_ID' => 84869,
                    'LIMIT' => 10,
                ]
            );
        
            $result = $response->getResponseData()->getResult();
            print_r($result);
        } catch (Throwable $e) {
            error_log($e->getMessage());
        }

BX24.callMethod(
            'im.dialog.messages.get',
            {
                DIALOG_ID: 'chat1489',
                FIRST_ID: 84869,
                LIMIT: 10
            },
            function(result)
            {
                if (result.error())
                {
                    console.error(result.error());
                }
                else
                {
                    console.log(result.data());
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'im.dialog.messages.get',
            [
                'DIALOG_ID' => 'chat1489',
                'FIRST_ID' => 84869,
                'LIMIT' => 10,
            ]
        );
        
        print_r($result);

Response Handling

HTTP Status: 200

{
            "result": {
                "chat_id": 1489,
                "messages": [
                    {
                        "id": 84877,
                        "chat_id": 1489,
                        "author_id": 503,
                        "date": "2026-03-04T09:43:26+02:00",
                        "text": "We are very glad to see you!",
                        "unread": false,
                        "uuid": "0c42a08f-4235-49fc-994f-c9bccd499ac1",
                        "replaces": [],
                        "params": {
                            "LIKE": [547]
                        },
                        "disappearing_date": null
                    },
                    {
                        "id": 84875,
                        "chat_id": 1489,
                        "author_id": 503,
                        "date": "2026-03-04T09:43:21+02:00",
                        "text": "Hello, Anna! Here we will discuss the project.",
                        "unread": false,
                        "uuid": "db2e826a-dd18-4ab5-b76c-4084e106ee28",
                        "replaces": [],
                        "params": [],
                        "disappearing_date": null
                    },
                    ...,
                    {
                        "id": 84869,
                        "chat_id": 1489,
                        "author_id": 0,
                        "date": "2026-03-04T09:42:31+02:00",
                        "text": "[USER=503 REPLACE]John Smith[/USER] invited to the chat [USER=547 REPLACE]Anna Johnson[/USER]",
                        "unread": false,
                        "uuid": null,
                        "replaces": [],
                        "params": {
                            "CODE": ["CHAT_JOIN"],
                            "NOTIFY": "N"
                        },
                        "disappearing_date": null
                    },
                    ...
                ],
                "users": [
                    {
                        "id": 503,
                        "active": true,
                        "name": "John Smith",
                        "first_name": "John",
                        "last_name": "Smith",
                        "work_position": "admin",
                        "color": "#4ba984",
                        "avatar": "https://mysite.com/upload/resize_cache/main/avatar.jpg",
                        "avatar_hr": "https://mysite.com/upload/resize_cache/main/avatar.jpg",
                        "gender": "M",
                        "birthday": "",
                        "extranet": false,
                        "network": false,
                        "bot": false,
                        "connector": false,
                        "external_auth_id": "socservices",
                        "status": "online",
                        "idle": false,
                        "last_activity_date": "2026-03-04T10:13:14+02:00",
                        "mobile_last_date": false,
                        "desktop_last_date": false,
                        "absent": false,
                        "departments": [667],
                        "phones": false,
                        "bot_data": null,
                        "type": "user",
                        "website": "",
                        "email": "smith@mysite.com"
                    },
                    {
                        "id": 547,
                        "active": true,
                        "name": "Anna Johnson",
                        "first_name": "Anna",
                        "last_name": "Johnson",
                        ...
                    }
                ],
                "files": [
                    {
                        "id": 5255,
                        "chatId": 1489,
                        "date": "2026-03-02T16:10:00+02:00",
                        "type": "image",
                        "name": "image.png",
                        "extension": "png",
                        "size": 2144,
                        "image": {
                            "height": 61,
                            "width": 72
                        },
                        "status": "done",
                        "progress": 100,
                        "authorId": 503,
                        "authorName": "John Smith",
                        "urlPreview": "https://mysite.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=5255&exact=N&_esd=s6P3x5qDBEKU0NiS7sczr69Y%2FHHR8Za8EXa7STOAXIVOylYhMsnMj5nGU0VXeQ1PIsqm%2F0GNxOju5wR1jNj76d%2FZnVgpyqeIcJ4UiWXm8CJsrmARXWpxWe%2BgJ%2BpGqx0M5CxgjNzIopQp2cwM&fileName=image.png",
                        "urlShow": "https://mysite.com/bitrix/services/main/ajax.php?action=disk.api.file.showImage&SITE_ID=s1&humanRE=1&fileId=5255&width=1280&height=1280&signature=4b6b2bbba680d3bccd8b70e398d94c1c3cfcb018f813089c32db3bb25df594f5&exact=N&_esd=s6P3x5qDBEKU0NiS7sczr69Y%2FHHR8Za8EXa7STOAXIVOylYhMsnMj5nGU0VXeQ1PIsqm%2F0GNxOju5wR1jNj76d%2FZnVgpyqeIcJ4UiWXm8CJsrmARXWpxWe%2BgJ%2BpGqx0M5CxgjNzIopQp2cwM&fileName=image.png",
                        "urlDownload": "https://mysite.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=5255&exact=N&_esd=s6P3x5qDBEKU0NiS7sczr69Y%2FHHR8Za8EXa7STOAXIVOylYhMsnMj5nGU0VXeQ1PIsqm%2F0GNxOju5wR1jNj76d%2FZnVgpyqeIcJ4UiWXm8CJsrmARXWpxWe%2BgJ%2BpGqx0M5CxgjNzIopQp2cwM&fileName=image.png",
                        "viewerAttrs": {
                            "viewer": "",
                            "viewerType": "image",
                            "src": "https://mysite.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=5255&exact=N&_esd=s6P3x5qDBEKU0NiS7sczr69Y%2FHHR8Za8EXa7STOAXIVOylYhMsnMj5nGU0VXeQ1PIsqm%2F0GNxOju5wR1jNj76d%2FZnVgpyqeIcJ4UiWXm8CJsrmARXWpxWe%2BgJ%2BpGqx0M5CxgjNzIopQp2cwM&fileName=image.png",
                            "viewerResized": "",
                            "objectId": "5255",
                            "viewerGroupBy": "1489",
                            "imChatId": 1489,
                            "title": "image.png",
                            "actions": "[{\"type\":\"download\"},{\"type\":\"copyToMe\",\"text\":\"Save to Drive\",\"action\":\"BXIM.disk.saveToDiskAction\",\"params\":{\"fileId\":\"5255\"},\"extension\":\"disk.viewer.actions\",\"buttonIconClass\":\"ui-btn-icon-cloud\"}]"
                        },
                        "mediaUrl": {
                            "preview": {
                                "250": "https://mysite.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=5255&exact=N&_esd=s6P3x5qDBEKU0NiS7sczr69Y%2FHHR8Za8EXa7STOAXIVOylYhMsnMj5nGU0VXeQ1PIsqm%2F0GNxOju5wR1jNj76d%2FZnVgpyqeIcJ4UiWXm8CJsrmARXWpxWe%2BgJ%2BpGqx0M5CxgjNzIopQp2cwM&fileName=image.png"
                            }
                        },
                        "isTranscribable": false,
                        "isVideoNote": false,
                        "isVoiceNote": false
                    }
                ]
            },
            "time": {
                "start": 1772608704,
                "finish": 1772608704.545697,
                "duration": 0.5456969738006592,
                "processing": 0,
                "date_start": "2026-03-04T10:18:24+02:00",
                "date_finish": "2026-03-04T10:18:24+02:00",
                "operating_reset_at": 1772609304,
                "operating": 0
            }
        }

Returned Data

Name `type`	Description
result `object`	Root element of the response (detailed description)
time `time`	Information about the request execution time

Object result

Name `type`	Description
chat_id `integer`	Identifier of the chat
messages `array`	Array of messages (detailed description). The method will return an empty array if a non-existent identifier is specified in `LAST_ID` or `FIRST_ID`.
users `array`	Users from the selection (detailed description). The method will return an empty array if a non-existent identifier is specified in `LAST_ID` or `FIRST_ID`.
files `array`	Files from the selection (detailed description). The method will return an empty array if a non-existent identifier is specified in `LAST_ID` or `FIRST_ID`.

Object message

Name `type`	Description
id `integer`	Identifier of the message
chat_id `integer`	Identifier of the chat
author_id `integer`	Identifier of the author, `0` for system messages
date `datetime`	Date of the message in ISO 8601 format
text `string`	Text of the message
unread `boolean`	Indicator of unread message
uuid `string`	Unique identifier of the message, `null` for system messages
replaces `array`	Array of text replacements for the message
params `object`	Additional parameters of the message (detailed description). The set of fields in the object depends on the type of message: regular or system.
disappearing_date `datetime`	Date of disappearance of the message, `null` if not set

Object params

Name `type`	Description
LIKE `array`	Identifiers of users who reacted to the message
CODE `array`	Codes of system events: `CHAT_JOIN` — user added to the chat `CHAT_LEAVE` — user left the chat
NOTIFY `string`	Indicator of notification sending. Value `N` — notification is not sent

Object user

Name `type`	Description
id `integer`	Identifier of the user
active `boolean`	Indicator of active user
name `string`	Full name
first_name `string`	First name
last_name `string`	Last name
work_position `string`	Job title
color `string`	Avatar color in hex format
avatar `string`	Link to the avatar
avatar_hr `string`	Link to the high-resolution avatar
gender `string`	Gender. `M` — male `F` — female
birthday `string`	Date of birth
extranet `boolean`	Indicator of extranet user
network `boolean`	Indicator of Bitrix24 network user
bot `boolean`	Indicator of bot
connector `boolean`	Indicator of Open Lines user
external_auth_id `string`	Type of authentication
status `string`	User status
idle `boolean`	Indicator of user inactivity
last_activity_date `datetime`	Date of last activity
mobile_last_date `datetime`	Date of last activity in the mobile app, `false` if the app was not used
desktop_last_date `datetime`	Date of last activity in the desktop app, `false` if the app was not used
absent `boolean`	Indicator of user absence
departments `array`	Identifiers of user departments
phones `object`	User phones, `false` if not specified
bot_data `object`	Bot data, `null` for regular users
type `string`	User type
website `string`	User website
email `string`	User e-mail

Object file

Name `type`	Description
id `integer`	Identifier of the file
chatId `integer`	Identifier of the chat
date `datetime`	Date of file upload
type `string`	Type of file: `image`, `video`, `audio`, `file`
name `string`	Name of the file
extension `string`	File extension
size `integer`	Size in bytes
image `object`	Dimensions of the image for files of type `image` (detailed description)
status `string`	Status of the file: `done` — uploaded
progress `integer`	Percentage of file upload
authorId `integer`	Identifier of the file author
authorName `string`	Name of the file author
urlPreview `string`	Link for file preview
urlShow `string`	Link for displaying the file
urlDownload `string`	Link for downloading the file
viewerAttrs `object`	Attributes for file viewer (detailed description)
mediaUrl `object`	Media file URL for preview (detailed description)
isTranscribable `boolean`	Indicator of transcribability
isVideoNote `boolean`	Indicator of video note
isVoiceNote `boolean`	Indicator of voice note

Object image

Name `type`	Description
height `integer`	Height of the image in pixels
width `integer`	Width of the image in pixels

Object viewerAttrs

Name `type`	Description
viewer `string`	Type of viewer
viewerType `string`	Type of file display
src `string`	Link to the file
viewerResized `string`	Link to the reduced version of the file
objectId `string`	Identifier of the file object
viewerGroupBy `string`	Identifier of the group for viewing files in the chat
imChatId `integer`	Identifier of the chat
title `string`	Name of the file
actions `string`	Available actions with the file in JSON format

Object mediaUrl

Name `type`	Description
preview `object`	Links for file preview. The keys of the object are the dimensions of the image in pixels

Error Handling

HTTP Status: 400

{
            "error": "DIALOG_ID_EMPTY",
            "error_description": "Dialog 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

Status	Code	Description	Value
`400`	`DIALOG_ID_EMPTY`	Dialog ID can't be empty	The `DIALOG_ID` parameter is not provided, is empty, or is in an incorrect format.
`400`	`FIRST_ID_STRING`	First ID can't be string	The `FIRST_ID` parameter is provided with a non-numeric value.
`400`	`LAST_ID_STRING`	Last ID can't be string	The `LAST_ID` parameter is provided with a non-numeric value.
`403`	`ACCESS_ERROR`	You do not have access to the specified dialog	The user does not have access to the dialog.

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 allowed to be called 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 methods must be called using the HTTPS protocol
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block, to remove it you need to contact Bitrix24 technical support
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	The REST API is available only on commercial plans
`403`	`INVALID_CREDENTIALS` Invalid request credentials	The user whose access token or webhook was used to call the method lacks 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 account administrator has allowed access to this application only for specific users
`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 option "Temporary closure of the public part of the site". Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Create Object Based on Message

Find Message in Chat

Get the List of Recent Messages im.dialog.messages.get

Method ParametersMethod Parameters

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Object resultObject result

Object messageObject message

Object paramsObject params

Object userObject user

Object fileObject file

Object imageObject image

Object viewerAttrsObject viewerAttrs

Object mediaUrlObject mediaUrl

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning