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. ru
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 or false Time of last activity. Arrives as false when there was 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": "ru",
      "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": false,
        "phones": false
      }
    ]
  }
}

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
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 are encoded differently. In data.users[] an empty field arrives in one of several forms depending on its type: an empty string "" (lastName, avatar, birthday, website, email), false (the dates lastActivityDate, mobileLastDate, desktopLastDate and the phones list), an empty array [] (departments). In data.bot an unset backgroundId arrives as null. Check a field's form before using it: new Date(false) and phones.map(...) on a false value produce incorrect results.

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