Register a bot

New OAuth bots support fetch and webhook. The platform verifies bot ownership through the same OAuth application and an exact id/code match, without sending botToken to the OAuth API. Delivery to /api/bot/webhook requires a recent, verified INSTALL/placement event from the linked application; otherwise registration returns 409 BOT_APP_EVENT_ENROLLMENT_REQUIRED. An earlier application token is not a substitute for this verification. Events received before initial registration completes are retained in a bounded encrypted inbox. Bot-token changes for new application-owned bots are refused (409 BOT_OAUTH_POLICY_INVALID); unmarked legacy bots are not automatically converted. A standalone OAuth key without a bound application can use fetch or its own receiver, but is not trusted by the platform receiver.

The platform receiver is available to Agent and ManagedBot bots with a verified owner. An application bot without a verified owner receives 409 BOT_APP_EVENT_CONSUMER_REQUIRED before any data is written to Bitrix24. It can use fetch or its own callback. Events for an already published bot after a Bitrix24 account address change may remain in encrypted quarantine until the recovered identity is verified and published. Delivery requires an unchanged callback binding, continued eligibility of the application, author and owner membership, and verified authority to deliver the recovered events. If that basis changes or cannot be verified, held events are permanently discarded while bot identity recovery continues. Bounded retention does not guarantee delivery. Each recovery can retain at most 256 events and 4 MiB of ciphertext for 72 hours. A duplicate event does not extend retention. On overflow, the receiver returns 503 without acknowledging receipt.

POST /v1/bots

Registers a bot in your Bitrix24 account. New registrations accept a personal key backed by an incoming webhook or an OAuth application key. Repeating registration for a bot already known to the platform preserves the bot's token. Ambiguous recovery and registration during an account address change return 409. Do not treat this response 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.

A Bitrix24 plan that includes Vibecode is also required. On a Bitrix24 account without such a plan, registration returns 422 BITRIX_ERROR with error.b24Code set to FEATURE_NOT_AVAILABLE_ON_CURRENT_PLAN, and retrying the request does not help. You can check the account's plan before the call: it is returned in the data.tariff field of GET /v1/me.

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

Use a key from the same OAuth application for both initial registration and repeat requests. The platform verifies bot ownership before saving it.

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

Use a key from the same OAuth application for both initial registration and repeat requests. The platform verifies bot ownership before saving it.

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 you know of another key belonging to the owner, see Bot access recovery.

Errors

Full list of common API errors — Errors.

Known specifics

Recovery after a desync. Without a local record, an existing ID or a code already in use does not prove bot ownership. For a personal key, Vibecode verifies acceptance of the new token. For OAuth, it verifies ownership by the same application. If ownership cannot be confirmed, the method returns 409 BOT_REGISTRATION_ORIGIN_UNPROVEN without creating a record. Repeat requests from the same OAuth application are accepted once ownership is confirmed.

Repeat requests that return 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. A retained local record carries data: { botId, code, needsReregistration: true } and Retry-After: 5; a move detected during the request has neither data nor Retry-After. Wait for recovery in both cases. 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. When creating a bot, pass parameters at the top level (code, name, color). PATCH accepts flat parameters or 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. A new OAuth registration is accepted once ownership by the same application is verified. If no previous local record exists, a caller-provided token is still rejected with 409 BOT_REGISTRATION_ORIGIN_UNPROVEN before the platform contacts Bitrix24. An expired legacy OAuth token requires a separate authorization refresh. Registration does not refresh these tokens and returns 409 BOT_REGISTRATION_CONTEXT_CHANGED. Previously created bots reporting BOT_OWNERSHIP_ERROR are not recovered automatically.

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 using a different key returns 403 BOT_ACCESS_DENIED. If a different key is the one that still works, see Bot access recovery. An app-owned OAuth bot can transfer only to an eligible key of the same OAuth application (client_id). Restore access to that matching application and key; a recreated application with another client_id cannot take ownership: 400 TARGET_KEY_INVALID with error.reason=application_mismatch. If the matching application cannot be restored, contact support. Unmarked legacy/token-based and personal-webhook bots retain their existing transfer rules and can use an eligible key of the same Bitrix24 account. Transfer to a compatible key preserves botId, chats and history.

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. For an Agent or ManagedBot bot with verified ownership and application enrollment, /api/bot/webhook receives events on the platform and delivers them through the owner's tunnel without making the server public. Details and solutions are in the Troubleshooting section. The incoming event body and its authenticity check are in A webhook-delivered event.

For your own receiver, choose the verification method based on how the bot was registered: personal-key bots and OAuth bots registered under the previous contract use the string custom followed immediately by the bot token; new application-owned OAuth bots use the top-level application token from verified enrollment, compared with trusted server-side configuration; data.bot.id is routing data, not an authentication pin. The platform separately verifies the bot ID and code when confirming ownership during registration. Using an OAuth key does not migrate a legacy bot. See Webhook authenticity.

See also

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