For AI agents: markdown of this page — /docs-content-en/bots/chats/get.md documentation index — /llms.txt

Get a chat

GET /v1/bots/:botId/chats/:dialogId

Returns chat information. The bot must be a member of the chat.

Parameters

Parameter Type Required Description
ParameterbotId (path) Typenumber Requiredyes DescriptionBot ID. List: GET /v1/bots
ParameterdialogId (path) Typestring Requiredyes DescriptionDialog ID. For a group chat, it is chatXXX, returned in the data.chat.dialogId field of the POST /v1/bots/:botId/chats response and in the chat.dialogId field of bot events. A number means a direct chat with the user who has that ID

Examples

curl — personal key

Terminal 
curl https://vibecode.bitrix24.com/v1/bots/42/chats/chat456 \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/bots/42/chats/chat456 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/chats/chat456', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Chat:', data.chat.name)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/chats/chat456', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

The table lists the main response fields.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe chat and its related data
Fielddata.chat Typeobject DescriptionChat object
Fielddata.chat.id Typenumber DescriptionNumeric chat ID in Bitrix24
Fielddata.chat.dialogId Typestring DescriptionDialog ID: chatXXX for a group chat, the other participant's numeric ID for a direct chat
Fielddata.chat.type Typestring DescriptionChat type: chat for a group chat, private for a direct chat
Fielddata.chat.messageType Typestring DescriptionChat type code: C for a group chat, P for a direct chat
Fielddata.chat.name Typestring DescriptionChat name. An empty string for a direct chat
Fielddata.chat.description Typestring DescriptionChat description. An empty string if not set
Fielddata.chat.owner Typenumber DescriptionChat owner ID. User list: GET /v1/users
Fielddata.chat.role Typestring DescriptionThe bot's role in the chat, for example owner or member
Fielddata.chat.managerList Typenumber[] DescriptionIDs of the chat managers
Fielddata.chat.userCounter Typenumber DescriptionNumber of participants in a group chat. 0 for a direct chat
Fielddata.chat.color Typestring DescriptionChat color in HEX, for example #4ba984
Fielddata.chat.avatar Typestring DescriptionAvatar URL. An empty string if no avatar is set
Fielddata.chat.entityType Typestring DescriptionLinked entity type. An empty string if the chat is not linked to anything
Fielddata.chat.entityId Typestring DescriptionLinked entity ID. An empty string if the chat is not linked to anything
Fielddata.chat.textFieldEnabled Typeboolean DescriptionWhether the input field is enabled. Toggled by Input field control
Fielddata.chat.permissions Typeobject DescriptionChat permissions. Keys are actions, for example manageUsersAdd, manageSettings, canPost. Values are the minimum role for the action: owner, manager, or member
Fielddata.chat.lastId Typenumber DescriptionID of the last message in the chat
Fielddata.chat.messageCount Typenumber DescriptionNumber of messages in the chat
Fielddata.chat.dateCreate Typestring DescriptionCreation date (ISO 8601)
Fielddata.users Typearray DescriptionUser profiles returned with the chat. This is not the chat membership: in a group chat created by the bot, the array contains only the bot. List participants returns the participants with the same profile fields
Fielddata.recentConfig Typeobject DescriptionWhere the chat appears in the recent chats list: chatId and the sections array
Fielddata.callInfo Typeobject DescriptionVideo call data for the chat: chatId and the token
Fielddata.parentChat Typeobject | null DescriptionParent chat. null if the chat is not nested in another chat
Fielddata.messagesAutoDeleteConfigs Typearray DescriptionMessage auto-delete settings. An empty array if auto-delete is not configured
Fielddata.copilot Typeobject | null DescriptionAI assistant data for a group chat. null if no assistant is connected. The field is absent from the response for a direct chat

Response example

Main fields are shown.

JSON 
{
  "success": true,
  "data": {
    "recentConfig": {
      "chatId": 456,
      "sections": ["default", "chat"]
    },
    "parentChat": null,
    "users": [
      {
        "id": 42,
        "active": true,
        "name": "Support",
        "bot": true,
        "type": "bot"
      }
    ],
    "copilot": null,
    "messagesAutoDeleteConfigs": [],
    "callInfo": {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
      "chatId": 456
    },
    "chat": {
      "id": 456,
      "dialogId": "chat456",
      "type": "chat",
      "messageType": "C",
      "name": "Support chat",
      "description": "Technical support channel",
      "owner": 42,
      "role": "owner",
      "managerList": [42],
      "userCounter": 2,
      "color": "#4ba984",
      "avatar": "",
      "entityType": "",
      "entityId": "",
      "textFieldEnabled": true,
      "permissions": {
        "manageUsersAdd": "member",
        "manageUsersDelete": "manager",
        "manageUi": "member",
        "manageSettings": "owner",
        "manageMessages": "member",
        "manageMessagesAutoDelete": "manager",
        "manageGuestInvites": "manager",
        "manageDelete": "member",
        "canPost": "member"
      },
      "lastId": 1505,
      "messageCount": 4,
      "dateCreate": "2026-10-19T10:28:34+00:00"
    }
  }
}

Error response example

403 — the bot is not a member of the chat:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "Access denied"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_BOT_ID DescriptionbotId is not a number
HTTP404 CodeBOT_NOT_FOUND DescriptionNo bot found with this ID
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot belongs to another API key
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe bot is not a member of the chat
HTTP422 CodeBITRIX_ERROR DescriptionAnother Bitrix24 error, text in message
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the imbot scope
HTTP410 CodeBOT_DISABLED DescriptionThe bot is disabled and does not process API calls. To restore the bot, see Bot disabled
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

See also