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
ParameterbotId Typenumber Requiredyes DescriptionBot 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
Fielddata.bot.id Typenumber DescriptionBot ID in the Bitrix24 account
Fielddata.bot.code Typestring DescriptionUnique bot code
Fielddata.bot.type Typestring DescriptionBot type: bot, personal, supervisor, openline
Fielddata.bot.isHidden Typeboolean DescriptionHidden from the contact list
Fielddata.bot.isSupportOpenline Typeboolean DescriptionOpen Channels support
Fielddata.bot.isReactionsEnabled Typeboolean DescriptionReactions to messages are allowed
Fielddata.bot.backgroundId Typestring DescriptionChat background. Arrives as null when not set
Fielddata.bot.language Typestring DescriptionBot language, e.g. en
Fielddata.bot.moduleId Typestring DescriptionThe module that registered the bot, e.g. rest
Fielddata.bot.eventMode Typestring DescriptionEvent mode: fetch or webhook
Fielddata.bot.countMessage Typenumber DescriptionMessage counter
Fielddata.bot.countCommand Typenumber DescriptionCommand counter
Fielddata.bot.countChat Typenumber DescriptionChat counter
Fielddata.bot.countUser Typenumber DescriptionUser counter
Fielddata.users[].id Typenumber DescriptionBot user ID. Matches data.bot.id
Fielddata.users[].name Typestring DescriptionFull name
Fielddata.users[].firstName Typestring DescriptionFirst name
Fielddata.users[].lastName Typestring DescriptionLast name. Empty string when not set
Fielddata.users[].workPosition Typestring DescriptionJob title
Fielddata.users[].color Typestring DescriptionAvatar color in HEX format, e.g. #29619b
Fielddata.users[].avatar Typestring DescriptionAvatar URL. Empty string when not set
Fielddata.users[].gender Typestring DescriptionGender: M or F
Fielddata.users[].active Typeboolean DescriptionWhether the user is active
Fielddata.users[].bot Typeboolean DescriptionBot flag
Fielddata.users[].departments Typearray DescriptionDepartments. Empty array when there are none
Fielddata.users[].lastActivityDate Typestring | null DescriptionTime 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
HTTP400 CodeINVALID_BOT_ID DescriptionbotId is not a number
HTTP404 CodeBOT_NOT_FOUND DescriptionBot not found — register it via POST /v1/bots
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot belongs to a different API key. To regain control, see Bot access recovery
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the imbot scope
HTTP410 CodeBOT_DISABLED DescriptionThe bot is disabled and does not process API calls. How to restore it — Bot disabled
HTTP401 CodeTOKEN_MISSING DescriptionThe 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