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

Get a bot

GET /v1/bots/:botId

Retrieves the current bot data from Bitrix24 (a live request, not from cache).

Parameters

Parameter Type Required Description
botId number yes Bot ID (path parameter)

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/bots/42 \
  -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', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Bot:', data)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

The response contains two objects: data.bot — the bot's parameters, data.users — an array of Bitrix24 users representing the bot. The array holds one element — the bot's user account.

Field Type Description
data.bot.id number Bot ID in the Bitrix24 account
data.bot.code string Unique bot code
data.bot.type string Bot type: bot, personal, supervisor, openline
data.bot.isHidden boolean Hidden from the contact list
data.bot.isSupportOpenline boolean Open Channels support
data.bot.isReactionsEnabled boolean Reactions to messages are allowed
data.bot.backgroundId string Chat background. Arrives as null when not set
data.bot.language string Bot language, e.g. en
data.bot.moduleId string The module that registered the bot, e.g. rest
data.bot.eventMode string Event mode: fetch or webhook
data.bot.countMessage number Message counter
data.bot.countCommand number Command counter
data.bot.countChat number Chat counter
data.bot.countUser number User counter
data.users[].id number Bot user ID. Matches data.bot.id
data.users[].name string Full name
data.users[].firstName string First name
data.users[].lastName string Last name. Empty string when not set
data.users[].workPosition string Job title
data.users[].color string Avatar color in HEX format, e.g. #29619b
data.users[].avatar string Avatar URL. Empty string when not set
data.users[].gender string Gender: M or F
data.users[].active boolean Whether the user is active
data.users[].bot boolean Bot flag
data.users[].departments array Departments. Empty array when there are none
data.users[].lastActivityDate string | null Time of last activity. null if there has been no activity

The data.users array also carries other standard Bitrix24 user fields — birthday, phones, website, email, status, mobileLastDate, desktopLastDate. How empty values are encoded is covered in "Known specifics".

Response example

JSON 
{
  "success": true,
  "data": {
    "bot": {
      "id": 42,
      "code": "support_bot",
      "type": "bot",
      "isHidden": false,
      "isSupportOpenline": false,
      "isReactionsEnabled": true,
      "backgroundId": null,
      "language": "en",
      "moduleId": "rest",
      "eventMode": "fetch",
      "countMessage": 0,
      "countCommand": 0,
      "countChat": 0,
      "countUser": 0
    },
    "users": [
      {
        "id": 42,
        "active": true,
        "name": "Support",
        "firstName": "Support",
        "lastName": "",
        "workPosition": "Technical support assistant",
        "color": "#29619b",
        "avatar": "",
        "gender": "M",
        "bot": true,
        "departments": [],
        "lastActivityDate": null,
        "phones": []
      }
    ]
  }
}

Error response example

404 — bot not found:

JSON 
{
  "success": false,
  "error": {
    "code": "BOT_NOT_FOUND",
    "message": "Bot 999 not found. Register it first via POST /v1/bots."
  }
}

Errors

HTTP Code Description
400 INVALID_BOT_ID botId is not a number
404 BOT_NOT_FOUND Bot not found — register it via POST /v1/bots
403 BOT_ACCESS_DENIED The bot belongs to a different API key. To take it back — Bot access recovery
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.

Known specifics

Empty values arrive in a predictable form. The platform normalizes the empty dates lastActivityDate, mobileLastDate and desktopLastDate to null, and an empty phones list to an empty array, so phones.map(...) works without a prior check. The string fields lastName, avatar, birthday, website, email arrive as an empty string when not set, departments as an empty array, and an unset backgroundId in data.bot as null.

Avatar color is returned in HEX. On write, color accepts a palette name (AZURE, MINT, …), but in the response data.users[].color arrives as a HEX string, e.g. #29619b. The written palette name cannot be read back.

See also