## 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](/docs/chats)) |

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

## 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](/docs/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

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