Get Chat Data im.dialog.get
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
Scope:
imWho can execute the method: any user — chat participant
The method im.dialog.get retrieves information about a chat.
Method Parameters
Required parameters are marked with *
|
Name |
Description |
|
DIALOG_ID* |
Chat identifier in the format:
Examples: |
Code Examples
How to Use Examples in Documentation
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"DIALOG_ID":"chat1435"}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/im.dialog.get
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"DIALOG_ID":"chat1435","auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/im.dialog.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 ImDialogGetResult = {
id: number
parent_chat_id: number
parent_message_id: number
name: string
description: string
owner: number
extranet: boolean
avatar: string
color: string
type: string
counter: number
user_counter: number
message_count: number
unread_id: number
restrictions: {
avatar: boolean
rename: boolean
extend: boolean
call: boolean
mute: boolean
leave: boolean
leave_owner: boolean
send: boolean
user_list: boolean
path: string
path_title: string
}
last_message_id: number
last_id: number
marked_id: number
disk_folder_id: number
entity_type: string
entity_id: string
entity_data_1: string
entity_data_2: string
entity_data_3: string
mute_list: number[]
date_create: ISODate
message_type: string
public: string
role: string
entity_link: {
type: string
url: string
id: string
}
text_field_enabled: boolean
background_id: number | null
permissions: {
manage_users_add: string
manage_users_delete: string
manage_ui: string
manage_settings: string
manage_messages: string
can_post: string
}
is_new: boolean
readed_list: {
user_id: number
user_name: string
message_id: number
date: ISODate | null
}[]
manager_list: number[]
last_message_views: {
message_id: number
first_viewers: number[]
count_of_viewers: number
}
dialog_id: string
}
try {
const response = await $b24.actions.v2.call.make<ImDialogGetResult>({
method: 'im.dialog.get',
params: {
DIALOG_ID: 'chat1435',
},
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('Dialog:', result.id, result.name, result.type, result.role)
}
} 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 getDialog() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v2.call.make({
method: 'im.dialog.get',
params: {
DIALOG_ID: 'chat1435',
},
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('Dialog:', result.id, result.name, result.type, result.role)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', getDialog)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.im.dialog.get(
dialog_id="chat1435",
).response
result = bitrix_response.result
print(result)
except BitrixAPIError as error:
print(
"Bitrix API error",
f"error: {error.error}",
f"error_description: {error.error_description}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Bitrix SDK error: {error.message}")
except Exception as error:
print(f"Unexpected error: {error}")
try {
$response = $b24Service
->core
->call(
'im.dialog.get',
[
'DIALOG_ID' => 'chat1435',
]
);
$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.get',
{
DIALOG_ID: 'chat1435'
},
function(result)
{
if (result.error())
{
console.error(result.error());
}
else
{
console.log(result.data());
}
}
);
require_once('crest.php');
$result = CRest::call(
'im.dialog.get',
[
'DIALOG_ID' => 'chat1435',
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "im.dialog.get", b24.Params{
"DIALOG_ID": "chat1435",
}, b24.WithIdempotent())
if err != nil {
return fmt.Errorf("im.dialog.get: %w", err)
}
var item struct {
ID b24.ID `json:"id"`
ParentChatID int `json:"parent_chat_id"`
ParentMessageID int `json:"parent_message_id"`
Name string `json:"name"`
Description string `json:"description"`
Owner int `json:"owner"`
}
if err := json.Unmarshal(res.Result, &item); err != nil {
return fmt.Errorf("parse response: %w", err)
}
fmt.Println(item.ID, item.ParentChatID)
Response Handling
HTTP Status: 200
{
"result": {
"id": 1439,
"parent_chat_id": 0,
"parent_message_id": 0,
"name": "Deal Chat",
"description": "Discussion about the deal",
"owner": 503,
"extranet": false,
"avatar": "",
"color": "#f76187",
"type": "crm",
"counter": 0,
"user_counter": 3,
"message_count": 3,
"unread_id": 0,
"restrictions": {
"avatar": false,
"rename": false,
"extend": true,
"call": true,
"mute": true,
"leave": true,
"leave_owner": false,
"send": true,
"user_list": true,
"path": "",
"path_title": ""
},
"last_message_id": 84477,
"last_id": 84477,
"marked_id": 0,
"disk_folder_id": 0,
"entity_type": "CRM",
"entity_id": "DEAL|1663",
"entity_data_1": "",
"entity_data_2": "",
"entity_data_3": "",
"mute_list": [],
"date_create": "2026-02-25T16:50:58+01:00",
"message_type": "C",
"public": "",
"role": "owner",
"entity_link": {
"type": "DEAL",
"url": "/crm/deal/details/1663/",
"id": "DEAL|1663"
},
"text_field_enabled": true,
"background_id": null,
"permissions": {
"manage_users_add": "member",
"manage_users_delete": "manager",
"manage_ui": "member",
"manage_settings": "owner",
"manage_messages": "member",
"can_post": "member"
},
"is_new": false,
"readed_list": [
{
"user_id": 103,
"user_name": "John Smith",
"message_id": 0,
"date": null
},
{
"user_id": 547,
"user_name": "Peter Johnson",
"message_id": 0,
"date": null
}
],
"manager_list": [
503
],
"last_message_views": {
"message_id": 84477,
"first_viewers": [],
"count_of_viewers": 0
},
"dialog_id": "chat1439"
},
"time": {
"start": 1772030091,
"finish": 1772030091.165223,
"duration": 0.1652228832244873,
"processing": 0,
"date_start": "2026-02-25T17:34:51+01:00",
"date_finish": "2026-02-25T17:34:51+01:00",
"operating_reset_at": 1772030691,
"operating": 0
}
}
Returned Data
|
Name |
Description |
|
result |
Root object containing chat data (detailed description) |
|
time |
Information about the request execution time |
Object result-item
|
Name |
Description |
|
id |
Chat identifier |
|
parent_chat_id |
Parent chat identifier |
|
parent_message_id |
Parent message identifier |
|
name |
Chat name |
|
description |
Chat description |
|
owner |
Chat owner identifier |
|
extranet |
Indicator of external extranet user participation |
|
avatar |
Link to the chat avatar |
|
color |
Chat color in HEX format |
|
type |
Chat type |
|
counter |
Unread message counter |
|
user_counter |
Number of chat participants |
|
message_count |
Number of messages in the chat |
|
unread_id |
Identifier of the first unread message |
|
restrictions |
Restrictions on actions in the chat (detailed description) |
|
last_message_id |
Identifier of the last message |
|
last_id |
Identifier of the last read message |
|
marked_id |
Identifier of the marked message |
|
disk_folder_id |
Identifier of the chat folder on Drive |
|
entity_type |
External code of the chat: type |
|
entity_id |
External code of the chat: identifier |
|
entity_data_1 |
External data 1 for the chat |
|
entity_data_2 |
External data 2 for the chat |
|
entity_data_3 |
External data 3 for the chat |
|
mute_list |
List of users with notifications disabled |
|
date_create |
Chat creation date in ATOM format |
|
message_type |
Type of chat messages |
|
public |
Indicator of chat public status |
|
role |
Current user's role in the chat |
|
entity_link |
Link to the related object (detailed description) |
|
text_field_enabled |
Availability of the message input field |
|
background_id |
Identifier of the chat background. If not specified, the value is |
|
permissions |
Permissions for actions in the chat (detailed description) |
|
is_new |
Indicator of a new dialog |
|
readed_list |
List of users and read statuses (detailed description) |
|
manager_list |
List of chat manager identifiers |
|
last_message_views |
Information about views of the last message (detailed description) |
|
dialog_id |
Identifier of the dialog passed in the |
Object restrictions
|
Name |
Description |
|
avatar |
Availability of avatar change |
|
rename |
Availability of name change |
|
extend |
Availability of chat extension |
|
call |
Availability of calls |
|
mute |
Availability of notifications mute |
|
leave |
Availability of leaving the chat |
|
leave_owner |
Availability of owner leaving the chat |
|
send |
Availability of message sending |
|
user_list |
Availability of viewing the participant list |
|
path |
Link to the chat |
|
path_title |
Text of the link to the chat |
Object entity_link
|
Name |
Description |
|
type |
Type of the related object |
|
url |
Link to the related object |
|
id |
Identifier of the related object |
Object permissions
Each field of the object shows which group of participants the action is available to:
member— all chat participantsmanager— the chat owner and administratorsowner— only the chat owner
|
Name |
Description |
|
manage_users_add |
Permission to add participants |
|
manage_users_delete |
Permission to remove participants |
|
manage_ui |
Permission to change the chat appearance: title, color, and avatar |
|
manage_settings |
Permission to manage chat settings |
|
manage_messages |
Permission to manage messages |
|
can_post |
Permission to send messages |
Object readed_list
|
Name |
Description |
|
user_id |
User identifier |
|
user_name |
User name |
|
message_id |
Identifier of the last read message |
|
date |
Read date. If not specified, the value is |
Object last_message_views
|
Name |
Description |
|
message_id |
Identifier of the message |
|
first_viewers |
List of first viewers |
|
count_of_viewers |
Number of views |
Error Handling
HTTP Status: 400
{
"error": "DIALOG_ID_EMPTY",
"error_description": "Dialog ID can't be empty"
}
|
Name |
Description |
|
error |
String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only |
|
error_description |
Error message for the developer. Do not show it to the end user without processing |
Possible Error Codes
|
Status |
Code |
Description |
Value |
|
|
|
Dialog ID can't be empty |
Required parameter |
|
|
|
You do not have access to the specified dialog |
Insufficient rights to view the dialog |
Statuses and System Error Codes
HTTP Status: 4xx, 5xx
The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.
|
Status |
Code |
Description |
|
|
|
An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The request intensity limit has been exceeded |
|
|
|
The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit |
|
|
|
The request contains no authorization data: neither an access token nor a webhook code was passed |
|
|
|
Methods are called over the HTTPS protocol only |
|
|
|
The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support |
|
|
|
REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — |
|
|
|
No active webhook with the specified user identifier and secret code was found |
|
|
|
No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope |
|
|
|
The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with |
|
|
|
The access token has expired |
|
|
|
The application is installed, but the Bitrix24 administrator has granted access to it only to specific users |
|
|
|
The public part of the site is closed. To open it 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 |