## Dialog details

`GET /v1/chats/:dialogId`

Returns data about a dialog — a private or 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](/docs/chats)). `chatN` is the `id` field of a row in [recent dialogs](/docs/chats/discovery/recent); a user ID comes from the [user list](/docs/entities/users/list) |
| `format` (query) | string | no | `v2` turns on the v2 mode — see "The v2 mode" below. Any other value is ignored and the response is unchanged |

**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](/docs/chats/messages/load) 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](/docs/access-rights).

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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()
```

### curl — the v2 mode

```bash
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.

| 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 used 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 |
| `data.chat` | object | The v2 mode: the chat card — `id`, `dialogId`, `name`, `type`, `owner`, `role`, `parentChatId`, `managerList`, `permissions` and other fields |
| `data.recentConfig` | object | The v2 mode: which sections of the chat list show the chat — `chatId` and `sections` |
| `data.parentChat` | object\|null | The v2 mode: a short card of the parent chat — see [parent chat](/docs/chats/management/parent). `null` when there is no parent or no access to it |
| `data.copilot` | object\|null | The v2 mode: the CoPilot roles in the chat. `null` outside CoPilot chats |
| `data.messagesAutoDeleteConfigs` | array | The v2 mode: message auto-deletion settings |
| `data.callInfo` | object | The v2 mode: call data of the chat — `chatId` and `token`, the current user's call token. The endpoint passes it through unchanged. Do not write it to logs |

## Response example

The "Favorites" dialog requested with `dialogId` = `me`:

```json
{
  "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:

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

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | The v2 mode only: a parameter other than `format` or a repeated parameter. Checked before any call to Bitrix24 |
| 422 | `BITRIX_ERROR` | Without `format`: the dialog is unavailable or does not exist — Bitrix24 returned an access error. In the v2 mode — a non-existent chat: the portal code is in `error.b24Code`: `CHAT_NOT_FOUND` |
| 502 | `ME_ALIAS_RESOLUTION_FAILED` | Failed to resolve the current user ID when using the `me` alias |
| 403 | `BITRIX_ACCESS_DENIED` | The v2 mode only: the user has no access to the chat — Bitrix24 refused with the `ACCESS_DENIED` code |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Read-only mode: the existing chat was not confirmed within the limited window of recent dialogs, or a creating or ambiguous alias was passed. The method that would create the chat is not sent to the portal |
| 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](/docs/errors).

## Known specifics

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

## See also

- [Chat discovery](/docs/chats/discovery)
- [Find a CRM entity chat](/docs/chats/discovery/find)
- [Recent dialogs](/docs/chats/discovery/recent)
- [Read messages](/docs/chats/messages/list)