## 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 |
|----------|-----|:-----:|---------|
| `botId` (path) | number | yes | Bot ID. List: [`GET /v1/bots`](/docs/bots/management/list) |
| `dialogId` (path) | string | yes | Dialog ID. For a group chat, it is `chatXXX`, returned in the `data.chat.dialogId` field of the [`POST /v1/bots/:botId/chats`](/docs/bots/chats/create) response and in the `chat.dialogId` field of [bot events](/docs/bots/events/bot-events). A number means a direct chat with the user who has that ID |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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 |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | The chat and its related data |
| `data.chat` | object | Chat object |
| `data.chat.id` | number | Numeric chat ID in Bitrix24 |
| `data.chat.dialogId` | string | Dialog ID: `chatXXX` for a group chat, the other participant's numeric ID for a direct chat |
| `data.chat.type` | string | Chat type: `chat` for a group chat, `private` for a direct chat |
| `data.chat.messageType` | string | Chat type code: `C` for a group chat, `P` for a direct chat |
| `data.chat.name` | string | Chat name. An empty string for a direct chat |
| `data.chat.description` | string | Chat description. An empty string if not set |
| `data.chat.owner` | number | Chat owner ID. User list: [`GET /v1/users`](/docs/entities/users/list) |
| `data.chat.role` | string | The bot's role in the chat, for example `owner` or `member` |
| `data.chat.managerList` | number[] | IDs of the chat managers |
| `data.chat.userCounter` | number | Number of participants in a group chat. `0` for a direct chat |
| `data.chat.color` | string | Chat color in HEX, for example `#4ba984` |
| `data.chat.avatar` | string | Avatar URL. An empty string if no avatar is set |
| `data.chat.entityType` | string | Linked entity type. An empty string if the chat is not linked to anything |
| `data.chat.entityId` | string | Linked entity ID. An empty string if the chat is not linked to anything |
| `data.chat.textFieldEnabled` | boolean | Whether the input field is enabled. Toggled by [Input field control](/docs/bots/ui/text-field) |
| `data.chat.permissions` | object | Chat permissions. Keys are actions, for example `manageUsersAdd`, `manageSettings`, `canPost`. Values are the minimum role for the action: `owner`, `manager`, or `member` |
| `data.chat.lastId` | number | ID of the last message in the chat |
| `data.chat.messageCount` | number | Number of messages in the chat |
| `data.chat.dateCreate` | string | Creation date (ISO 8601) |
| `data.users` | array | User 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](/docs/bots/chats/user-list) returns the participants with the same profile fields |
| `data.recentConfig` | object | Where the chat appears in the recent chats list: `chatId` and the `sections` array |
| `data.callInfo` | object | Video call data for the chat: `chatId` and the `token` |
| `data.parentChat` | object \| null | Parent chat. `null` if the chat is not nested in another chat |
| `data.messagesAutoDeleteConfigs` | array | Message auto-delete settings. An empty array if auto-delete is not configured |
| `data.copilot` | object \| null | AI 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 |
|------|-----|---------|
| 400 | `INVALID_BOT_ID` | `botId` is not a number |
| 404 | `BOT_NOT_FOUND` | No bot found with this ID |
| 403 | `BOT_ACCESS_DENIED` | The bot belongs to another API key |
| 403 | `BITRIX_ACCESS_DENIED` | The bot is not a member of the chat |
| 422 | `BITRIX_ERROR` | Another Bitrix24 error, text in `message` |
| 403 | `SCOPE_DENIED` | The API key does not have the `imbot` scope |
| 410 | `BOT_DISABLED` | The bot is disabled and does not process API calls. To restore the bot, see [Bot disabled](/docs/bots/troubleshooting#bot-disabled-bot_disabled) |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## See also

- [Update a chat](/docs/bots/chats/update)
- [List participants](/docs/bots/chats/user-list)
- [Bot platform](/docs/bots)
- [Limits and optimization](/docs/optimization)