For AI agents: markdown of this page — /docs-content-en/bots/management/update.md documentation index — /llms.txt

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)

Parameter (flat) Parameter (Bitrix24 format) Type Description
name fields.properties.name string New bot name
lastName fields.properties.lastName string New last name
workPosition fields.properties.workPosition string New job title
color fields.properties.color string New avatar color
gender fields.properties.gender string Gender: M or F
avatar fields.properties.avatar string Bot avatar: PNG or JPEG as a base64 string without the data:image/...;base64, prefix, up to ~50 KB. See "Known specifics"
eventMode fields.eventMode string Event mode: fetch or webhook
webhookUrl fields.webhookUrl string URL for push notifications
isHidden fields.isHidden boolean Hide from the contact list
isReactionsEnabled fields.isReactionsEnabled boolean Allow reactions
backgroundId fields.backgroundId string Chat background: azure, mint, steel, slate, teal, cornflower, sky, peach, frost
isSupportOpenline fields.isSupportOpenline boolean Open Channels support (only for type: "openline")

Examples

curl — personal key

Terminal 
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

Terminal 
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

javascript 
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

javascript 
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

Field Type Description
data.bot object The updated bot. The field set matches the registration response
data.bot.id number Bot ID in the Bitrix24 account
data.bot.code string System bot code
data.bot.type string Bot type: bot, personal, or supervisor
data.bot.eventMode string Event delivery mode: fetch or webhook
data.users array The bot's card as a Bitrix24 account user

Response example

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

JSON 
{
  "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:

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

Errors

HTTP Code Description
400 INVALID_BOT_ID botId is not a number
404 BOT_NOT_FOUND Bot not found
403 BOT_ACCESS_DENIED The bot belongs to a different API key
403 SCOPE_DENIED The API key does not have the imbot scope
401 TOKEN_MISSING The API key has no configured tokens

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.

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