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 record (the same one as POST /v1/bots) and the Bitrix24 format with a fields wrapper. If the body contains fields, the request is forwarded to Bitrix24 unchanged. Otherwise the known top-level fields are automatically expanded into fields.properties.* / fields.*. The behavior of both forms is identical.

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. If the body contains a fields key, the platform forwards it to Bitrix24 unchanged. Otherwise it normalizes the flat fields itself.

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

Your own bot token is needed only if it is already fixed on your integration side. The platform issues the token itself at registration, and that value passes 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 do not pass 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. Size — up to ~50 KB: on excess, 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