## Обновить бота

`PATCH /v1/bots/:botId`

Обновляет свойства бота. Передавайте только те поля, которые хотите изменить.

> **Две формы тела запроса — обе корректны.** Платформа принимает как **плоскую** запись (та же, что у `POST /v1/bots`), так и формат Битрикс24 с обёрткой `fields`. Если в теле есть `fields`, запрос передаётся в Битрикс24 без изменений. Иначе известные поля верхнего уровня автоматически разворачиваются в `fields.properties.*` / `fields.*`. Поведение обеих форм идентично.

## Поля запроса (body)

| Параметр (плоский) | Параметр (формат Битрикс24) | Тип | Описание |
|---|---|-----|---------|
| `name` | `fields.properties.name` | string | Новое имя бота |
| `lastName` | `fields.properties.lastName` | string | Новая фамилия |
| `workPosition` | `fields.properties.workPosition` | string | Новая должность |
| `color` | `fields.properties.color` | string | Новый цвет аватара |
| `gender` | `fields.properties.gender` | string | Пол: `M` или `F` |
| `avatar` | `fields.properties.avatar` | string | Аватар бота: PNG или JPEG как base64-строка без префикса `data:image/...;base64,`, до ~50 КБ. См. «Известные особенности» |
| `eventMode` | `fields.eventMode` | string | Режим событий: `fetch` или `webhook` |
| `webhookUrl` | `fields.webhookUrl` | string | URL для push-уведомлений |
| `isHidden` | `fields.isHidden` | boolean | Скрыть из списка контактов |
| `isReactionsEnabled` | `fields.isReactionsEnabled` | boolean | Разрешить реакции |
| `backgroundId` | `fields.backgroundId` | string | Фон чата: `azure`, `mint`, `steel`, `slate`, `teal`, `cornflower`, `sky`, `peach`, `frost` |
| `isSupportOpenline` | `fields.isSupportOpenline` | boolean | Поддержка открытых линий (только для `type: "openline"`) |
| — | `fields.botToken` | string | Свой токен бота вместо выданного платформой: от 32 до 40 символов из алфавита `[A-Za-z0-9_-]`. Значение вне этих границ отклоняется с `400 BOT_TOKEN_INVALID` до вызова портала, и токен бота не меняется. Принимается только в форме с `fields` — плоского имени у поля нет. См. «Известные особенности» |

## Примеры

### curl — личный ключ

```bash
curl -X PATCH https://vibecode.bitrix24.tech/v1/bots/42 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "properties": { "name": "Новое имя", "color": "MINT" },
      "eventMode": "fetch"
    }
  }'
```

### curl — OAuth-приложение

```bash
curl -X PATCH https://vibecode.bitrix24.tech/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": "Новое имя", "color": "MINT" },
      "eventMode": "fetch"
    }
  }'
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/bots/42', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      properties: { name: 'Новое имя', color: 'MINT' },
      eventMode: 'fetch',
    },
  }),
})
const { data } = await res.json()
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/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: 'Новое имя', color: 'MINT' },
      eventMode: 'fetch',
    },
  }),
})
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `data.bot` | object | Обновлённый бот. Набор полей совпадает с ответом [регистрации](/docs/bots/management/create) |
| `data.bot.id` | number | ID бота на портале Битрикс24 |
| `data.bot.code` | string | Системный код бота |
| `data.bot.type` | string | Тип бота: `bot`, `personal` или `supervisor` |
| `data.bot.eventMode` | string | Режим доставки событий: `fetch` или `webhook` |
| `data.users` | array | Карточка бота как пользователя портала |

## Пример ответа

Показаны основные поля. Полный набор полей бота — в ответе [регистрации](/docs/bots/management/create).

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

## Пример ответа при ошибке

403 — бот принадлежит другому ключу:

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_BOT_ID` | `botId` не является числом |
| 400 | `BOT_TOKEN_INVALID` | `fields.botToken` короче 32 или длиннее 40 символов, содержит символы вне `[A-Za-z0-9_-]` либо передан не строкой. Портал не вызывается, токен бота остаётся прежним |
| 404 | `BOT_NOT_FOUND` | Бот не найден |
| 403 | `BOT_ACCESS_DENIED` | Бот принадлежит другому API-ключу |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `imbot` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Симметрия с регистрацией.** PATCH принимает как плоское тело (`{ name, eventMode, ... }`), так и формат Битрикс24 с обёрткой `fields` — так же, как `POST /v1/bots`. Если в теле есть ключ `fields`, платформа передаёт его в Битрикс24 без изменений. Иначе нормализует плоские поля сама.

**`type` нельзя изменить:** поле `type` не принимается при обновлении.

**Свой токен бота нужен, только если он уже зафиксирован на стороне вашей интеграции.** Платформа выдаёт токен сама при регистрации, и это значение границы проходит по построению. Задавать своё значение имеет смысл лишь тогда, когда интеграция уже завязана на конкретный токен. Этим же значением аутентифицируются события, которые Битрикс24 присылает боту, поэтому берите случайное значение длиной от 32 символов, например 32 шестнадцатеричных символа. Осмысленные строки вроде `support-bot-2026` границу не проходят.

**Формат аватара.** Поле `avatar` принимает изображение PNG или JPEG в виде base64-строки **без** префикса `data:image/...;base64,` — передавайте только сами base64-данные. Строка с префиксом `data:` приводит к ответу 422. Размер — до ~50 КБ: при превышении запрос завершается успешно (`success: true`), но аватар не сохраняется и в боте остаётся пустым. Эндпоинт принимает только JSON — загрузка файла через `multipart/form-data` не поддерживается (ответ 415). Передавайте значение как `avatar` (плоская форма) либо как `fields.properties.avatar` (форма с `fields`) — результат одинаковый.

## Смотрите также

- [Получить бота](/docs/bots/management)
- [Зарегистрировать бота](/docs/bots/management)
- [Бот-платформа](/docs/bots)
- [Лимиты и оптимизация](/docs/optimization)