Update a bot

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 answers 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

Symmetry with registration. PATCH accepts both a flat body ({ name, eventMode, ... }) and the Bitrix24 format with a fields wrapper — just like POST /v1/bots. Which body the platform treats as a wrapper and which it expands itself is described at the top of the page.

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 answers on a disabled bot, because it is handled before the BOT_DISABLED check and makes no Bitrix24 call:

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 answers 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. Which recovery path to pick is described in Bot disabled: this call only clears the state and the authorization-error counter, while /reauth additionally verifies access.

Your own bot token is needed only if your integration is already pinned to a specific token. The platform issues the token itself at registration, and that value is within the bounds by construction. Setting your own value makes sense only when the integration is already tied to a specific token. The same value authenticates the events Bitrix24 delivers to the bot, so use a random value at least 32 characters long — for example 32 hexadecimal characters. Meaningful strings such as support-bot-2026 fall outside the bounds.

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