Get Message History of the Dialogue imopenlines.session.history.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: imopenlines

Who can execute the method: any user

The method imopenlines.session.history.get returns the message history of an open line session.

Method Parameters

Required parameters are marked with *

Name
type

Description

SESSION_ID
integer

Identifier of the open line session.

The identifier can be obtained using the imopenlines.dialog.get method from the entity_data_1 field. The SESSION_ID identifier is located in the sixth parameter of the entity_data_1 string. For example, for "entity_data_1":"Y|LEAD|1205|N|N|321|1773223732|0|0|0", the session identifier is 321

CHAT_ID
integer

Numeric identifier of the open line chat without the chat prefix. For example, 1763, not chat1763.

The identifier can be obtained using the imopenlines.dialog.get or imopenlines.crm.chat.get methods

The method accepts one of the parameters: SESSION_ID or CHAT_ID.

If SESSION_ID is provided, the method operates based on it.
If SESSION_ID is not provided, the method attempts to determine the last session by CHAT_ID with sorting ID DESC.

In practice, for stable results, it is recommended to provide SESSION_ID.

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 '{"SESSION_ID":321}' \
          https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imopenlines.session.history.get

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"SESSION_ID":321,"auth":"**put_access_token_here**"}' \
          https://**put_your_bitrix24_address**/rest/imopenlines.session.history.get

try {
            const response = await $b24.callMethod(
                'imopenlines.session.history.get',
                {
                    SESSION_ID: 321,
                }
            );
        
            const { result } = response.getData();
            console.log(result);
        } catch (error) {
            console.error(error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'imopenlines.session.history.get',
                    [
                        'SESSION_ID' => 321,
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            if ($result->error()) {
                echo 'Error: ' . $result->error();
            } else {
                echo 'Success: ' . print_r($result->data(), true);
            }
        } catch (Throwable $exception) {
            error_log($exception->getMessage());
            echo 'Error getting session history: ' . $exception->getMessage();
        }

BX24.callMethod(
            'imopenlines.session.history.get',
            {
                SESSION_ID: 321,
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error().ex);
                } else {
                    console.log(result.data());
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'imopenlines.session.history.get',
            [
                'SESSION_ID' => 321,
            ]
        );
        
        if (!empty($result['error'])) {
            echo 'Error: ' . $result['error_description'];
        } else {
            echo 'Success: ' . print_r($result['result'], true);
        }

Response Handling

HTTP Status: 200

{
            "result": {
                "chatId": 1763,
                "canJoin": "Y",
                "canVoteHead": "Y",
                "sessionId": 321,
                "sessionVoteHead": 0,
                "sessionCommentHead": null,
                "userId": "chat1763",
                "message": {
                    "85851": {
                        "id": "85851",
                        "chatid": "1763",
                        "senderid": "103",
                        "recipientid": "chat1763",
                        "date": "2026-03-11T13:12:46+01:00",
                        "text": "Open the task card and click Observers",
                        "textlegacy": "Open the task card and click Observers",
                        "params": {
                            "connectorMid": ["85853"],
                            "fileId": [5437]
                        }
                    },
                    "85833": {
                        "id": "85833",
                        "chatid": "1763",
                        "senderid": "0",
                        "recipientid": "chat1763",
                        "date": "2026-03-11T13:09:25+01:00",
                        "text": "[b]A new lead has been created[/b]",
                        "textlegacy": "<b>A new lead has been created</b>",
                        "params": {
                            "attach": [
                                {
                                    "id": 1773223765,
                                    "blocks": [
                                        {
                                            "link": [
                                                {
                                                    "name": "Filling out the CRM form \"Contact Data Form for Open Lines\"",
                                                    "link": "/crm/lead/details/1205/"
                                                }
                                            ]
                                        },
                                        {
                                            "grid": [
                                                {
                                                    "display": "ROW",
                                                    "name": "Name",
                                                    "value": "John",
                                                    "colorToken": "base"
                                                },
                                                {
                                                    "display": "LINE",
                                                    "name": "Phone",
                                                    "value": "+11234567890",
                                                    "height": 20,
                                                    "colorToken": "base"
                                                }
                                            ]
                                        }
                                    ],
                                    "description": "",
                                    "color": "#df532d"
                                }
                            ]
                        }
                    },
                    ... // description for each message
                },
                "usersMessage": {
                    "chat1763": [
                        "85851",
                        "85833",
                    ]
                },
                "users": {
                    "103": {
                        "id": "103",
                        "name": "Samantha Johnson",
                        "active": true,
                        "firstName": "Samantha",
                        "lastName": "Johnson",
                        "workPosition": "IT Department Head",
                        "color": "#4ba984",
                        "avatar": "https://example.bitrix24.com/upload/main/avatar.png",
                        "avatarId": "8644",
                        "birthday": "08-03",
                        "gender": "F",
                        "phoneDevice": false,
                        "phones": false,
                        "extranet": false,
                        "network": false,
                        "bot": false,
                        "connector": false,
                        "profile": "/company/personal/user/103/",
                        "externalAuthId": "socservices",
                        "status": "online",
                        "idle": false,
                        "lastActivityDate": "2026-03-11T13:14:35+01:00",
                        "mobileLastDate": false,
                        "desktopLastDate": false,
                        "departments": [1, 7],
                        "absent": false,
                        "type": "user",
                        "services": null,
                        "botData": null
                    },
                    ... // description for each user
                },
                "openlines": {
                    "canvoteashead": {
                        "22": true
                    }
                },
                "userInGroup": {
                    "1": {
                        "id": 1,
                        "users": ["103"]
                    },
                    ... // description for each department
                },
                "woUserInGroup": [],
                "chat": {
                    "1763": {
                        "id": "1763",
                        "parentChatId": 0,
                        "parentMessageId": 0,
                        "name": "John - Bitrix24 Documentation",
                        "owner": "103",
                        "color": "#ba9c7b",
                        "extranet": false,
                        "avatar": "/bitrix/js/im/images/blank.gif",
                        "call": "0",
                        "callNumber": "",
                        "entityType": "LINES",
                        "entityId": "livechat|22|1761|587",
                        "entityData1": "Y|LEAD|1205|N|N|321|1773223732|0|0|0",
                        "entityData2": "LEAD|1205|COMPANY|0|CONTACT|0|DEAL|0",
                        "entityData3": "",
                        "messageCount": 14,
                        "public": "",
                        "muteList": {
                            "103": false,
                            "587": false
                        },
                        "managerList": [103],
                        "dateCreate": "2026-03-11T12:08:52+01:00",
                        "type": "lines",
                        "entityLink": {
                            "type": "LINES",
                            "url": "",
                            "id": "livechat|22|1761|587"
                        },
                        "permissions": {
                            "manageUsersAdd": "member",
                            "manageUsersDelete": "manager",
                            "manageUi": "member",
                            "manageSettings": "owner",
                            "manageMessages": "member",
                            "canPost": "member"
                        },
                        "textFieldEnabled": true,
                        "backgroundId": null,
                        "messageType": "L",
                        "isNew": false
                    }
                },
                "userBlockChat": {
                    "1763": {
                        "103": false,
                        "587": false
                    }
                },
                "userInChat": {
                    "1763": [103, 587]
                },
                "files": {
                    "5437": {
                        "id": 5437,
                        "chatid": 1763,
                        "date": "2026-03-11T13:12:46+01:00",
                        "type": "image",
                        "name": "2311.png",
                        "extension": "png",
                        "size": 70855,
                        "image": {
                            "height": 615,
                            "width": 646
                        },
                        "status": "done",
                        "progress": 100,
                        "authorid": 103,
                        "authorname": "Samantha Johnson",
                        "urlpreview": "https://some-domain.bitrix24.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=5437&exact=N&_esd=oYQLNdHU%3D&fileName=2311.png",
                        "urlshow": "https://some-domain.bitrix24.com/bitrix/services/main/ajax.php?action=disk.api.file.showImage&SITE_ID=s1&humanRE=1&fileId=5437&width=1280&height=1280&signature=d1007a9ed47599e2160b993ca&exact=N&_esd=oYQLNdHU%3D&fileName=2311.png",
                        "urldownload": "https://some-domain.bitrix24.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=5437&exact=N&_esd=oYQLNdHU%3D&fileName=2311.png",
                        "viewerattrs": {
                            "viewer": "",
                            "viewertype": "image",
                            "src": "https://some-domain.bitrix24.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=5437&exact=N&_esd=oYQLNdHU%3D&fileName=2311.png",
                            "viewerresized": "",
                            "objectid": "5437",
                            "viewergroupby": "1763",
                            "imchatid": 1763,
                            "title": "2311.png",
                            "actions": "[{\"type\":\"download\"},{\"type\":\"copyToMe\",\"text\":\"Save to Drive\",\"action\":\"BXIM.disk.saveToDiskAction\",\"params\":{\"fileId\":\"5437\"},\"extension\":\"disk.viewer.actions\",\"buttonIconClass\":\"ui-btn-icon-cloud\"}]"
                        },
                        "mediaurl": {
                            "preview": {
                                "250": "https://some-domain.bitrix24.com/bitrix/services/main/ajax.php?action=disk.api.file.showImage&SITE_ID=s1&humanRE=1&fileId=5437&width=250&height=250&signature=c28f11fbae0ee5a0c40970c4e8e554&exact=Y&_esd=oYQLNdHU%3D&fileName=2311.png"
                            }
                        },
                        "istranscribable": false,
                        "isvideonote": false,
                        "isvoicenote": false
                    }
                }
            },
            "time": {
                "start": 1773224138,
                "finish": 1773224138.143344,
                "duration": 0.14334392547607422,
                "processing": 0,
                "date_start": "2026-03-11T13:15:38+01:00",
                "date_finish": "2026-03-11T13:15:38+01:00",
                "operating_reset_at": 1773224738,
                "operating": 0
            }
        }

Returned Data

Name
type

Description

result
object

Root object of the response.

The structure of the object is described in detail below

time
time

Information about the execution time of the request

Result Object

Name `type`	Description
chatId `integer`	Identifier of the chat
canJoin `string`	Flag indicating the ability to join the dialogue: `Y` or `N`
canVoteHead `string`	Flag indicating the ability to evaluate operators by the supervisor: `Y` or `N`
sessionId `integer`	Identifier of the session
sessionVoteHead `integer`	Rating given by the supervisor
sessionCommentHead `string`	Supervisor's comment on the rating or `null`
userId `string`	Identifier of the chat in the format `chat<ID>`
message `object`	Chat messages indexed by message identifier. The structure of the object is described in detail below
usersMessage `object`	Relationship between the chat and the list of message identifiers. The structure of the object is described in detail below
users `object`	Object of chat participants, where the key is the user identifier. The structure of the object is described in detail below
openlines `object`	Open line data. The structure of the object is described in detail below
userInGroup `object`	Users grouped by departments, or an empty array The structure of the object is described in detail below
woUserInGroup `array`	Users not included in the departments from `userInGroup`
chat `object`	Chat data by its identifier. The structure of the object is described in detail below
userBlockChat `object`	Flags for blocking the chat by users. The structure of the object is described in detail below
userInChat `object`	Composition of chat participants or an empty array. The structure of the chat participants is described in detail below
files `object`	Files associated with messages, or an empty array. The structure of the files object is described in detail below

Message Object

Name
type

Description

object

Message object.

The structure of the message object is described in detail below

Message Item Object

Name `type`	Description
id `string`	Identifier of the message
chatid `string`	Identifier of the chat
senderid `string`	Identifier of the sender
recipientid `string`	Recipient of the message in the format `chat<ID>`
date `datetime`	Date and time of the message in ISO 8601 format (RFC3339)
text `string`	Text of the message
textlegacy `string`	Text of the message in legacy format
params `object`	Service parameters of the message

Users Message Object

Name `type`	Description
chat<chatId> `array`	Array of message identifiers related to the chat

Users Object

Name
type

Description

<userId>
object

User data.

The structure of the user object is described in detail below

User Item Object

Name `type`	Description
id `string`	Identifier of the user
name `string`	User's full name
firstName `string`	User's first name
lastName `string`	User's last name
workPosition `string`	Position or `null`
avatar `string`	Link to the user's avatar
avatarId `integer`	Identifier of the avatar file or `null`
gender `string`	User's gender
extranet `boolean`	Extranet user flag
connector `boolean`	Connector user flag
profile `string`	Link to the profile
externalAuthId `string`	External authentication type
status `string`	Online status or `null`
lastActivityDate `datetime`	Date and time of the last activity in ISO 8601 format (RFC3339)
departments `array`	Identifiers of departments
type `string`	Type of user

Open Lines Object

Name `type`	Description
canvoteashead `object`	Object of the form `{"<CONFIG_ID>": <boolean>}`, where the key is the identifier of the open line settings `CONFIG_ID`, and the value `true/false` indicates whether the supervisor can evaluate the operator's work in the session of this line

User In Group Object

Name
type

Description

<departmentId>
object

Department data.

The structure of the department object is described in detail below

Group Item Object

Name `type`	Description
id `integer`	Identifier of the department
users `array`	List of user identifiers that belong to the department

Chat Object

Name
type

Description

<chatId>
object

Chat data.

The structure of the department object is described in detail below

Chat Item Object

Name `type`	Description
id `string`	Identifier of the chat
name `string`	Name of the chat
owner `string`	Identifier of the chat owner
entityType `string`	Type of the chat object
entityId `string`	External identifier of the chat
entityData1 `string`	String with chat metadata
entityData2 `string`	Additional chat metadata
entityData3 `string`	Additional chat metadata
messageCount `integer`	Number of messages in the chat
public `string`	Public flag of the chat
muteList `object`	Object where the key is the user identifier, and the value `true/false` indicates whether notifications are turned off for this user in the chat
managerList `array`	List of identifiers of operator-managers
dateCreate `datetime`	Date and time of chat creation in ISO 8601 format (RFC3339)
type `string`	Type of chat
entityLink `object`	Data linking the chat to the open line
permissions `object`	Access rights in the chat
textFieldEnabled `boolean`	Flag indicating the availability of the message input field
backgroundId `integer`	Identifier of the chat background or `null`
messageType `string`	Type of chat messages
isNew `boolean`	Flag indicating a new chat

User Block Chat Object

Name `type`	Description
<chatId> `object`	Object with flags for blocking users in the chat: key — user identifier, value — `true` or `false`

User In Chat Object

Name `type`	Description
<chatId> `array`	Array of user identifiers that are in the chat

Files Object

Name
type

Description

<fileId>
object

File data.

The structure of the object is described in detail below

File Item Object

Name `type`	Description
id `integer`	Identifier of the file
chatid `integer`	Identifier of the chat
date `datetime`	Date and time of upload in ISO 8601 format (RFC3339)
type `string`	Type of file
name `string`	Name of the file
extension `string`	File extension
size `integer`	Size of the file in bytes
image `object`	Image parameters (`width`, `height`)
status `string`	Status of file processing
progress `integer`	Processing progress in percentage
authorid `integer`	Identifier of the file author
authorname `string`	Name of the file author
urlpreview `string`	URL of the file preview
urlshow `string`	URL of the file view
urldownload `string`	URL of the file download
viewerattrs `object`	Viewing parameters of the file in the interface
mediaurl `string`	URL of the media file
istranscribable `boolean`	Flag indicating the availability of file transcription
isvideonote `boolean`	Flag indicating a video note
isvoicenote `boolean`	Flag indicating a voice note

Error Handling

HTTP Status: 400

{
            "error": "MISSING_REQUIRED_PARAM",
            "error_description": "Session ID or Chat ID must be provided"
        }

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
`MISSING_REQUIRED_PARAM`	Session ID or Chat ID must be provided	`SESSION_ID` and `CHAT_ID` are not provided
`INVALID_SESSION_ID`	Unable to determine session ID from provided parameters	Unable to determine session from the provided parameters
`ACCESS_DENIED`	You cannot open this conversation as you do not have sufficient rights	Insufficient rights to view history, session not found or unavailable

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

Join a Dialog

Take Over Dialog from Current Operator

Get Message History of the Dialogue imopenlines.session.history.get

Method ParametersMethod Parameters

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Result ObjectResult Object

Message ObjectMessage Object

Message Item ObjectMessage Item Object

Users Message ObjectUsers Message Object

Users ObjectUsers Object

User Item ObjectUser Item Object

Open Lines ObjectOpen Lines Object

User In Group ObjectUser In Group Object

Group Item ObjectGroup Item Object

Chat ObjectChat Object

Chat Item ObjectChat Item Object

User Block Chat ObjectUser Block Chat Object

User In Chat ObjectUser In Chat Object

Files ObjectFiles Object

File Item ObjectFile Item Object

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning

Method Parameters

Code Examples

Response Handling

Returned Data

Result Object

Message Object

Message Item Object

Users Message Object

Users Object

User Item Object

Open Lines Object

User In Group Object

Group Item Object

Chat Object

Chat Item Object

User Block Chat Object

User In Chat Object

Files Object

File Item Object

Error Handling

Possible Error Codes

Statuses and System Error Codes

Continue Learning