Update a bot

New OAuth bots support fetch and webhook. The platform verifies bot ownership using the same OAuth application and the bot's exact ID and code, without sending botToken to the OAuth API. Delivery to /api/bot/webhook requires a recent, verified INSTALL/placement of the bound application; otherwise registration returns 409 BOT_APP_EVENT_ENROLLMENT_REQUIRED. A previously issued application token does not replace 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's 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.

PATCH /v1/bots/:botId

Updates a bot's properties. Pass only the fields you want to change.

Two body forms — both valid. The platform accepts both a flat body (the same as for POST /v1/bots) and the Bitrix24 format with a fields wrapper. If the body contains a non-empty fields wrapper, the request is forwarded to Bitrix24 unchanged. The values [], null, false, 0 and "" do not count as a wrapper — the body is read as flat. An empty object {} does count as a wrapper: it disables the expansion, and top-level fields are not applied. Without a wrapper, the known top-level fields are automatically expanded into fields.properties.* / fields.*, and an unrecognized key is dropped by that expansion — Bitrix24 would ignore it anyway. For every field that Bitrix24 applies, the behavior of both forms is identical.

The one exception is disabled. That field is handled by the platform itself and never travels to Bitrix24, so it is read only from the top level of the body. Inside the fields wrapper it is not a platform field at all: {"fields": {"disabled": false}} goes down the ordinary update path, and on a disabled bot that path returns 410 BOT_DISABLED. The re-enable call is the flat body {"disabled": false} and nothing else.

Request fields (body)

Examples

curl — personal key

curl -X PATCH https://vibecode.bitrix24.com/v1/bots/42 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "properties": { "name": "New name", "color": "MINT" },
      "eventMode": "fetch"
    }
  }'

curl — OAuth application

curl -X PATCH https://vibecode.bitrix24.com/v1/bots/42 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "properties": { "name": "New name", "color": "MINT" },
      "eventMode": "fetch"
    }
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      properties: { name: 'New name', color: 'MINT' },
      eventMode: 'fetch',
    },
  }),
})
const { data } = await res.json()

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      properties: { name: 'New name', color: 'MINT' },
      eventMode: 'fetch',
    },
  }),
})

Response fields

Response example

The main fields are shown. The full set of bot fields is in the registration response.

{
  "success": true,
  "data": {
    "bot": {
      "id": 42,
      "code": "my_helper_bot",
      "type": "bot",
      "eventMode": "fetch",
      "isHidden": false,
      "isReactionsEnabled": true,
      "language": "en"
    },
    "users": []
  }
}

Error response example

403 — the bot belongs to a different key:

{
  "success": false,
  "error": {
    "code": "BOT_ACCESS_DENIED",
    "message": "This bot belongs to a different API key"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

Request body format. Like POST /v1/bots, PATCH accepts a flat body ({ name, eventMode, ... }). It also accepts the Bitrix24 format with a fields wrapper. See the top of the page for how the platform detects a wrapper and when it expands a flat body.

type cannot be changed: the type field is not accepted on update.

Re-enabling a disabled bot. {"disabled": false} in the flat body is the only API call that clears the disabled state without /reauth — and the only call this endpoint handles for a disabled bot. The platform processes it before the BOT_DISABLED check without calling Bitrix24:

curl -X PATCH https://vibecode.bitrix24.com/v1/bots/42 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disabled": false}'

{ "success": true, "data": { "id": "cm3k9x2a10001qz7f8h2b4d6e", "disabled": false } }

In this response, id is the string identifier of the bot record on the platform, not the botId from the path. The response carries no bot and no users — nothing was read from Bitrix24. On an already enabled bot the call is a no-op and returns the same body. The fields form does not work here: {"fields": {"disabled": false}} is forwarded to Bitrix24 as an ordinary update, so on a disabled bot it returns 410 BOT_DISABLED and the bot stays disabled. disabled: true is never accepted (400 DISABLE_NOT_ALLOWED) — to retire a bot, use DELETE /v1/bots/:botId. See Bot disabled for guidance on choosing a recovery path. This call only clears the state and the authorization-error counter, while /reauth additionally verifies access.

The following token guidance applies to personal-key bots and OAuth bots registered under the previous contract.

Set your own bot token when your receiver needs a known verification value. The platform generates a token at registration and does not return it in API responses. For personal-key bots and OAuth bots registered under the previous contract, Bitrix24 sends custom followed by the bot token in auth.application_token; see Webhook authenticity. Use a random value of 32 to 40 characters — for example 32 hexadecimal characters. Descriptive strings such as support-bot-2026 do not meet these requirements. New application-owned OAuth bots use the application token instead and reject fields.botToken with 409 BOT_OAUTH_POLICY_INVALID.

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. A string with the data: prefix results in a 422 response. The maximum size is ~50 KB: if the limit is exceeded, the request completes successfully (success: true), but the avatar is not saved and the bot's avatar remains empty. The endpoint accepts JSON only — file upload via multipart/form-data is not supported (415 response). Pass the value as avatar (flat form) or as fields.properties.avatar (the fields form) — the result is the same.

See also

• Get a bot
• Register a bot
• Bot platform
• Limits and optimization