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

Dialog details

GET /v1/chats/:dialogId

Returns data about the dialog: title, type, unread counter, access settings, and the linked CRM entity (if any). Accepts a numeric dialogId for a private chat or chatN for a group chat.

Parameters

Parameter Type Required Description
dialogId (path) string yes Dialog identifier. Numeric ID for a private chat (1), chatN for a group chat (chat42), or the literal me — the current user (see Section overview)

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/chats/1 \
  -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/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

javascript 
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()

Response fields

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

Field Type Description
success boolean Always true on success
data object Dialog object
data.id number Dialog identifier
data.name string Chat title
data.description string Chat description
data.type string Dialog type: private — private, chat — group, open — open channel
data.owner number Owner ID. Source: GET /v1/users
data.color string Chat color in #rrggbb format
data.avatar string Chat avatar URL
data.counter number Number of unread messages for the current user
data.userCounter number Number of members
data.messageCount number Total number of messages in the chat
data.lastId number ID of the last message. Used as a cursor in GET /v1/chats/:dialogId/messages
data.dialogId string Dialog identifier in the format accepted by Bitrix24
data.dateCreate string Creation date (ISO 8601)
data.role string Role of the current user: owner, manager, member
data.entityType string Type of the linked CRM entity (CRM, FAVORITE, etc.) or an empty string
data.entityId string Identifier of the linked CRM entity or an empty string
data.restrictions object Action restrictions in the chat (see below)
data.permissions object Chat management permissions (see below)
data.restrictions.avatar boolean The current user can change the avatar
data.restrictions.rename boolean The current user can rename the chat
data.restrictions.extend boolean The current user can invite members
data.restrictions.call boolean The current user can initiate a call
data.restrictions.leave boolean The current user can leave the chat
data.restrictions.send boolean The current user can send messages
data.permissions.manageUsersAdd string Who can add members: owner, manager, member
data.permissions.manageUsersDelete string Who can remove members
data.permissions.manageSettings string Who can change chat settings
data.permissions.canPost string Who can send messages

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 253,
    "name": "Project discussion",
    "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": "",
    "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:

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

Errors

HTTP Code Description
422 BITRIX_ERROR The dialog is unavailable or does not exist — Bitrix24 returned an access error
502 ME_ALIAS_RESOLUTION_FAILED Failed to resolve the current user ID when using the me alias
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no configured tokens

The full list of general API errors — Errors.

Known specifics

  • A numeric dialogId opens a private chat with a user (or the "Favorites" dialog when dialogId equals the current user's ID). A group chat is addressed by the string chatN, where N is the numeric group ID.
  • An unavailable or non-existent dialog returns 422 BITRIX_ERROR, not 404. This is the observable behavior of the endpoint.

See also