Retrieve a List of Recent Messages im.dialog.messages.get

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 im.dialog.messages.get method retrieves messages from the specified conversation, including system messages. It does not support standard pagination due to the potentially large volume of data.

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

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`	Message identifier relative to which older messages should be loaded. The method will return messages with an identifier smaller than the specified one. To sequentially load history backwards, first request the latest messages without `LAST_ID` and `FIRST_ID`. Then pass to `LAST_ID` the minimum `id` from the received `messages` array
FIRST_ID `integer`	Message identifier relative to which newer messages should be loaded. The method will return messages with an identifier larger than the specified one. For example, with `FIRST_ID=123` and `LIMIT=10`, the method will return up to 10 messages with an identifier larger than `123`. To receive messages added after the already uploaded sample, pass to `FIRST_ID` the maximum `id` from the received `messages` array
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 latest messages of the dialogue, taking into account `LIMIT`. The method may return more messages than specified in `LIMIT` if there are unread messages in the chat. Default — `20`. The maximum value is —`50`

Code Examples

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

JS (TS)

JS (UMD)

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

// 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 DialogMessagesGetResult = {
          chat_id: number
          messages: {
            id: number
            chat_id: number
            author_id: number
            date: ISODate
            text: string
            unread: boolean
            uuid: string | null
            replaces: unknown[]
            params: Record<string, unknown>
            disappearing_date: ISODate | null
          }[]
          users: {
            id: number
            active: boolean
            name: string
            first_name: string
            last_name: string
            status: string
            last_activity_date: ISODate
            type: string
          }[]
          files: {
            id: number
            chatId: number
            date: ISODate
            type: string
            name: string
            size: number
            status: string
            authorId: number
            authorName: string
            urlDownload: string
            isTranscribable: boolean
            isVideoNote: boolean
            isVoiceNote: boolean
          }[]
        }
        
        try {
          const response = await $b24.actions.v2.call.make<DialogMessagesGetResult>({
            method: 'im.dialog.messages.get',
            params: {
              DIALOG_ID: 'chat1489',
              FIRST_ID: 84869,
              LIMIT: 10,
            },
            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(result.chat_id, 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 getDialogMessages() {
            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.get',
                params: {
                  DIALOG_ID: 'chat1489',
                  FIRST_ID: 84869,
                  LIMIT: 10,
                },
                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(result.chat_id, result.messages.length, result.messages)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', getDialogMessages)
        </script>

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);

// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "im.dialog.messages.get", b24.Params{
        	"DIALOG_ID": "chat1489",
        	"FIRST_ID":  84869,
        	"LIMIT":     10,
        }, b24.WithIdempotent())
        if err != nil {
        	return fmt.Errorf("im.dialog.messages.get: %w", err)
        }
        
        // The response arrives as json.RawMessage — unmarshal it
        // into a struct matching the response shape shown below on this page.
        fmt.Printf("%s\n", res.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+03:00",
                        "text": "We are very happy to have 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+03:00",
                        "text": "Hello, Anna! We will discuss the project here.",
                        "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+03:00",
                        "text": "[USER=503 REPLACE]Klaus Weber[/USER] invited [USER=547 REPLACE]Anna Weber[/USER] to the chat",
                        "unread": false,
                        "uuid": null,
                        "replaces": [],
                        "params": {
                            "CODE": ["CHAT_JOIN"],
                            "NOTIFY": "N"
                        },
                        "disappearing_date": null
                    }
                ],
                "users": [
                    {
                        "id": 503,
                        "active": true,
                        "name": "Klaus Weber",
                        "first_name": "Klaus",
                        "last_name": "Weber",
                        "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+03:00",
                        "mobile_last_date": false,
                        "desktop_last_date": false,
                        "absent": false,
                        "departments": [667],
                        "phones": false,
                        "bot_data": null,
                        "type": "user",
                        "website": "",
                        "email": "ivanov@mysite.com"
                    },
                    {
                        "id": 547,
                        "active": true,
                        "name": "Anna Weber",
                        "first_name": "Anna",
                        "last_name": "Weber",
                        "work_position": "Manager",
                        "color": "#df532d",
                        "avatar": "",
                        "avatar_hr": "",
                        "gender": "F",
                        "birthday": "",
                        "extranet": false,
                        "network": false,
                        "bot": false,
                        "connector": false,
                        "external_auth_id": "default",
                        "status": "online",
                        "idle": false,
                        "last_activity_date": "2026-03-04T10:11:02+03:00",
                        "mobile_last_date": false,
                        "desktop_last_date": false,
                        "absent": false,
                        "departments": [667],
                        "phones": false,
                        "bot_data": null,
                        "type": "user",
                        "website": "",
                        "email": "weber@mysite.com"
                    }
                ],
                "files": [
                    {
                        "id": 5255,
                        "chatId": 1489,
                        "date": "2026-03-02T16:10:00+03:00",
                        "type": "image",
                        "name": "image.png",
                        "extension": "png",
                        "size": 2144,
                        "image": {
                            "height": 61,
                            "width": 72
                        },
                        "status": "done",
                        "progress": 100,
                        "authorId": 503,
                        "authorName": "Klaus Weber",
                        "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 Disk\",\"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+03:00",
                "date_finish": "2026-03-04T10:18:24+03: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

Result Object

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`

Message Object

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

Params Object

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

User Object

Name `type`	Description
id `integer`	User identifier
active `boolean`	Indicator of an active user
name `string`	Full name
first_name `string`	First Name
last_name `string`	Last Name
work_position `string`	Position
color `string`	Avatar color in hex format
avatar `string`	Link to avatar
avatar_hr `string`	Link to the high-resolution avatar
gender `string`	Gender. `M` — male `F` — female
birthday `string`	Date of birth
extranet `boolean`	Extranet user status
network `boolean`	Indicator of Bitrix24 network user
bot `boolean`	Indicator of a bot
connector `boolean`	Indicator of an Open Channels user
external_auth_id `string`	Type of authentication
status `string`	User's 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`	Type of user
website `string`	User's website
email `string`	User e-mail

File Object

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`	File name
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

Image Object

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

viewerAttrs Object

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`	File name
actions `string`	Available actions with the file in JSON format

mediaUrl Object

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 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

Was the article helpful?

Create Object Based on Message

Find Message in Chat

Retrieve a List of Recent Messages im.dialog.messages.get

Method ParametersMethod Parameters

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Result ObjectResult Object

Message ObjectMessage Object

Params ObjectParams Object

User ObjectUser Object

File ObjectFile Object

Image ObjectImage Object

viewerAttrs ObjectviewerAttrs Object

mediaUrl ObjectmediaUrl Object

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning