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

```bash
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

```bash
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](/docs/bots/management/create) 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](/docs/bots/management/create) 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](/docs/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

- [Get a bot](/docs/bots/management)
- [Register a bot](/docs/bots/management)
- [Bot platform](/docs/bots)
- [Limits and optimization](/docs/optimization)