Dialog details

GET /v1/chats/:dialogId

Returns data about a dialog — a private or a group chat.

Parameters

The v2 mode. format=v2 reads the chat. data carries the object { chat, recentConfig, parentChat, copilot, messagesAutoDeleteConfigs, callInfo } with camelCase keys: chat is the chat card with permissions but without the old counter, restrictions and readedList; the rest is the chat context. The mode accepts only format. Any other parameter or a repeated parameter is rejected with 400 INVALID_PARAMS. The v2 mode may make you a member: when the chat allows auto-join — a comment chat, a collab or a task chat, for example — the call adds the current user as a member, as loading a chat does. In the v2 mode this targeted read operation is available to a READONLY key only when it is an employee's personal key with the im scope. It does not mark messages as read by itself.

Read-only key. In READONLY mode, this request reads an existing chat: pass its chatN, or a numeric peer ID confirmed in the same employee's recent dialogs. For me, the check looks for an existing personal dialog. The check scans at most 4000 raw rows of recent dialogs. If the binding is not confirmed, the request returns 403 WRITE_BLOCKED_READONLY_KEY without calling a method that could create a chat. The check's limits and the permitted read effects are described in access rights.

Examples

curl — personal key

curl https://vibecode.bitrix24.com/v1/chats/1 \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/1', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Dialog:', data.name, 'type:', data.type)

JavaScript — OAuth application

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

curl — the v2 mode

curl "https://vibecode.bitrix24.com/v1/chats/chat42?format=v2" \
  -H "X-Api-Key: YOUR_API_KEY"

Response fields

The main fields are shown. The response contains the full dialog object.

Response example

The "Favorites" dialog requested with dialogId = me:

{
  "success": true,
  "data": {
    "id": 253,
    "name": "Favorites",
    "description": "",
    "owner": 1,
    "type": "private",
    "color": "#4ba984",
    "avatar": "",
    "counter": 0,
    "userCounter": 1,
    "messageCount": 1,
    "lastId": 9357,
    "dialogId": "1",
    "dateCreate": "2024-03-15T10:30:00+00:00",
    "role": "owner",
    "entityType": "FAVORITE",
    "entityId": "",
    "restrictions": {
      "avatar": true,
      "rename": true,
      "extend": true,
      "call": true,
      "mute": true,
      "leave": true,
      "leaveOwner": true,
      "send": true,
      "userList": true
    },
    "permissions": {
      "manageUsersAdd": "member",
      "manageUsersDelete": "manager",
      "manageUi": "member",
      "manageSettings": "owner",
      "manageMessages": "member",
      "canPost": "member"
    }
  }
}

Error response example

422 — the dialog is unavailable or does not exist:

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "You do not have access to the specified dialog"
  }
}

Errors

The full list of general API errors — Errors.

Known specifics

• A numeric dialogId equal to the current user's ID opens the "Favorites" dialog.

See also

• Chat discovery
• Find a CRM entity chat
• Recent dialogs
• Read messages