#Bot management

Register a bot on 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 a 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. Registration via POST /v1/bots is allowed and does not require an admin role on the Bitrix24 side — the restriction is set by the permissions of your webhook/OAuth token.

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

#Errors

Full list of common API errors — Errors.

#Known specifics

Type cannot be changed: after registration, type is fixed. PATCH /v1/bots/:botId does not accept this field.

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.

Body format differs from PATCH: on creation, fields are passed flat (code, name, color). On update — 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. Size is up to ~50 KB: above that the request succeeds, but the avatar is not saved and stays empty.

Idempotency on code: if a bot with this code already exists both in the Vibecode database and in the Bitrix24 account, 409 BOT_ALREADY_EXISTS is returned with data: { botId, code, name } of the existing bot. Suitable for re-running scripts and verifying registration without handling 200/400 separately.

Bot lifecycle. A bot exists exactly as long as the local application through which it was registered exists. 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. Polling events, sending messages, and updating run with that same key — a request from a different key returns 403 BOT_ACCESS_DENIED. To move a bot to another active key of the same user — or by an account admin — use POST /v1/bots/:botId/transfer.

webhook mode requires a public webhookUrl. With eventMode: "webhook", Bitrix24 sends events directly to webhookUrl, so the address must be publicly reachable. A Black Hole server with the OWNER_ONLY policy does not accept such a request — details and the solution are in the Troubleshooting section.

#See also

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