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

Get a chat

GET /v1/bots/:botId/chats/:dialogId

Returns chat information. The bot must be a participant of the chat.

Parameters

Parameter Type Req. Description
botId (path) number yes Bot ID
dialogId (path) string yes Dialog ID: chatXXX for group chats, the numeric user ID for direct chats

Examples

curl — personal key

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

curl — OAuth application

Terminal 
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.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

Field Type Description
id number Chat ID
dialogId string Dialog ID (chatXXX)
type string Chat type
name string Chat name
description string Description
owner number Owner ID
avatar string Avatar URL
color string Chat color
entityType string Linked entity type
entityId string Linked entity ID
dateCreate string Creation date (ISO 8601)

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 456,
    "dialogId": "chat456",
    "type": "chat",
    "name": "Support chat",
    "description": "Technical support channel",
    "owner": 42,
    "avatar": "",
    "color": "AZURE",
    "entityType": "",
    "entityId": "",
    "dateCreate": "2026-03-31T10:30:00+00:00"
  }
}

Error response example

502 — the bot is not a participant of the chat:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "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
502 BITRIX_ERROR Bitrix24 error (the bot is not a chat participant)
403 SCOPE_DENIED The API key does not have the imbot scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

See also