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

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

#Примеры

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

Terminal 
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-приложение

Terminal 
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 Обновлённый бот. Набор полей совпадает с ответом регистрации
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 Карточка бота как пользователя портала

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

Показаны основные поля. Полный набор полей бота — в ответе регистрации.

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 не является числом
404 BOT_NOT_FOUND Бот не найден
403 BOT_ACCESS_DENIED Бот принадлежит другому API-ключу
403 SCOPE_DENIED API-ключ не имеет скоупа imbot
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

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

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

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

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

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