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 bot in your Bitrix24 account. New registrations require a personal key backed by an incoming webhook. Repeating a known registration preserves its token. Ambiguous recovery and registration during an account address change return 409 and must not be treated as confirmation that the bot works.

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

Only for repeating a bot registration already known locally. This method cannot create a new registration through OAuth.

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

Only for repeating a bot registration already known locally. This method cannot create a new registration through OAuth.

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 contains botId, code, and name only when the record is already known locally. Absence from GET /v1/bots does not prove that no earlier registration exists in the Bitrix24 account. If another owner key is known, see Bot access recovery.

Errors

Full list of common API errors — Errors.

Known specifics

Recovery after a desync. Without a local record, an existing Bitrix24 ID or an occupied code does not prove a new registration. Vibecode checks acceptance of the new token in a separate request. Unproven origin returns 409 BOT_REGISTRATION_ORIGIN_UNPROVEN without creating a record. For a new registration, use a unique code and a personal key backed by an incoming webhook.

Repeat call answered with 201. The previous token is preserved when the bot was known locally before the request and Bitrix24 returns the same registration. After an account address change, replaying that registration does not clear needsReregistration: the response is 409 BOT_DOMAIN_REREGISTRATION_REQUIRED with data: { botId, code, needsReregistration: true }. The record is retained. Never delete Agent or Managed Bot identities through the Bot API. Recover them through their owner resource, or contact support if that recovery is unavailable.

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.

OAuth and caller-provided tokens. Without a previous local record, OAuth and caller-provided tokens are refused before registration: 409 BOT_REGISTRATION_ORIGIN_UNPROVEN is returned before contacting Bitrix24. For a known record, an expired legacy OAuth token requires a separate authorization refresh. This operation does not refresh it and returns 409 BOT_REGISTRATION_CONTEXT_CHANGED.

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. The incoming event body and its authenticity check are in A webhook-delivered event.

See also

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