Bot management

Register a bot in your Bitrix24 account, fetch and update its data, restore access after authorization failures, and delete the bot when it's no longer needed.

Scope: imbot | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Register a bot

POST /v1/bots

Registers a new bot in your Bitrix24 account. The operation is idempotent on code — a repeated call with the same code returns 409 BOT_ALREADY_EXISTS with the data of the existing bot.

Request fields (body)

Bot types

⚠ personal and supervisor are privileged types: they receive all messages in the chats they belong to, even without an @mention of the bot. Use them deliberately.

Bot registration is performed on behalf of a Bitrix24 account administrator, regardless of the bot type. If the key owner does not have that role, Bitrix24 denies access even when the key carries the imbot scope.

Available colors

Used in the color parameter when creating and updating a bot:

RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK,
LIME, BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE

Examples

curl — personal key

curl -X POST https://vibecode.bitrix24.com/v1/bots \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "support_bot",
    "name": "Support",
    "type": "bot",
    "eventMode": "fetch",
    "color": "AZURE",
    "workPosition": "Technical support assistant"
  }'

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/bots \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "support_bot",
    "name": "Support",
    "type": "bot",
    "eventMode": "fetch",
    "color": "AZURE",
    "workPosition": "Technical support assistant"
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/bots', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'support_bot',
    name: 'Support',
    type: 'bot',
    eventMode: 'fetch',
    color: 'AZURE',
    workPosition: 'Technical support assistant',
  }),
})

const { success, data } = await res.json()
// `data.botId` mirrors the 409 BOT_ALREADY_EXISTS response — the same path for
// success and conflict. `data.bot.id` is kept for backward compatibility.
console.log('Bot ID:', data.botId)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/bots', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'support_bot',
    name: 'Support',
    type: 'bot',
    eventMode: 'fetch',
    color: 'AZURE',
    workPosition: 'Technical support assistant',
  }),
})

const { success, data } = await res.json()

Response fields

Response example

{
  "success": true,
  "data": {
    "botId": 42,
    "bot": {
      "id": 42,
      "code": "support_bot",
      "type": "bot",
      "eventMode": "fetch",
      "isHidden": false,
      "isReactionsEnabled": true
    },
    "users": [
      {
        "id": 42,
        "name": "Support",
        "active": true,
        "bot": true
      }
    ]
  }
}

Error response example

409 — a bot with this code already exists:

{
  "success": false,
  "error": {
    "code": "BOT_ALREADY_EXISTS",
    "message": "Bot with this code already exists"
  },
  "data": {
    "botId": 42,
    "code": "support_bot",
    "name": "Support"
  }
}

The data field returns the botId, code, and name of the already-registered bot — this is the idempotent path for recovering the record in the Vibecode database after a desync. If a bot with that botId is missing from GET /v1/bots under your key, it was registered with a different key on the same Bitrix24 account: the procedure for regaining control is in Bot access recovery.

Errors

Full list of common API errors — Errors.

Known specifics

Recovery after a desync: if the bot exists in the Bitrix24 account but is missing from the Vibecode database (after a failure), a repeated POST with the same code restores the database record.

Request body format differs from PATCH: on creation, fields are passed flat (code, name, color). On update, they are passed as a nested structure { fields: { properties: { name, color } } }.

Avatar format. The avatar field accepts a PNG or JPEG image as a base64 string without the data:image/...;base64, prefix — pass only the base64 data itself. An image URL or a string with the data: prefix results in a 422 BITRIX_ERROR response. The maximum size is ~50 KB: above that the request still succeeds, but the avatar is not saved and stays empty.

Idempotency on code: a repeat request is safe when a bot with this code already exists both in the Vibecode database and in the Bitrix24 account. Suitable for re-running scripts and verifying registration without handling success and conflict separately.

Bot lifecycle. A bot lives exactly as long as the local application through which it was registered. Removing the application from the Bitrix24 account also removes the bot.

Bot operations use the same key. A bot is bound to the API key it was registered with. Fetching events, sending messages, and updating the bot all use that same key — a request from a different key returns 403 BOT_ACCESS_DENIED. If a different key is the one that still works, see Bot access recovery.

webhook mode requires a public webhookUrl. With eventMode: "webhook", Bitrix24 sends events directly to webhookUrl, so the address must be publicly reachable. If webhookUrl points at a Black Hole server with a personal vibe_api_… key, only the PUBLIC access policy accepts the event — under OWNER_ONLY (the default), NAMED_USERS, DEPARTMENT, PORTAL, and AUTHENTICATED it never reaches the app, and eventMode: "fetch" suits such a server better. A server whose key is bound to an OAuth application accepts events under any policy. Details and solutions are in the Troubleshooting section.

See also

• Troubleshooting
• Events
• Messages
• Update a bot
• Transfer bot ownership
• Bot access recovery
• Bot platform
• Limits and optimization