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

PATCH /v1/bots/:botId

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

Две формы тела запроса — обе корректны. Платформа принимает как плоскую запись (та же, что у POST /v1/bots), так и формат Битрикс24 с обёрткой fields. Если в теле есть непустая обёртка fields, запрос передаётся в Битрикс24 без изменений. Значения [], null, false, 0 и "" обёрткой не считаются — тело читается как плоское. Пустой объект {} обёрткой считается: он отключает разворачивание, и поля верхнего уровня применены не будут. Без обёртки известные поля верхнего уровня автоматически разворачиваются в fields.properties.* / fields.*, а неизвестный ключ при таком разворачивании отбрасывается — Битрикс24 всё равно его игнорировал. Для всех полей, которые применяет Битрикс24, поведение обеих форм идентично.

Единственное исключение — disabled. Это поле платформа применяет сама и в Битрикс24 не передаёт, поэтому читает его только с верхнего уровня тела. Внутри обёртки fields оно полем платформы не является: {"fields": {"disabled": false}} уходит по обычному пути обновления, а на отключённом боте этот путь отвечает 410 BOT_DISABLED. Вызов возврата бота — это плоское тело {"disabled": false}, и только оно.

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

Примеры

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

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

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 — личный ключ

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

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',
    },
  }),
})

Поля ответа

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

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

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

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

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

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

Ошибки

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

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

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

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

Возврат отключённого бота. {"disabled": false} в плоском теле — единственный вызов API, который снимает отключение без /reauth, и единственный вызов этого эндпоинта, который отключённый бот обрабатывает: он отвечает до проверки BOT_DISABLED и Битрикс24 не вызывает:

curl -X PATCH https://vibecode.bitrix24.tech/v1/bots/42 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disabled": false}'

{ "success": true, "data": { "id": "cm3k9x2a10001qz7f8h2b4d6e", "disabled": false } }

id в этом ответе — строковый идентификатор записи бота на платформе, а не botId из пути. В ответе нет ни bot, ни users — из Битрикс24 ничего не читалось. На уже включённом боте вызов ничего не меняет и возвращает то же тело. Форма с fields здесь не работает: {"fields": {"disabled": false}} уходит в Битрикс24 как обычное обновление, поэтому на отключённом боте отвечает 410 BOT_DISABLED, а бот остаётся отключённым. disabled: true не принимается никогда (400 DISABLE_NOT_ALLOWED) — чтобы убрать бота, используйте DELETE /v1/bots/:botId. Какой путь восстановления выбрать, описано в Бот отключён: этот вызов только снимает состояние и счётчик ошибок авторизации, а /reauth ещё и проверяет доступ.

Свой токен бота нужен, только если он уже зафиксирован на стороне вашей интеграции. Платформа выдаёт токен сама при регистрации, и это значение границы проходит по построению. Задавать своё значение имеет смысл лишь тогда, когда интеграция уже завязана на конкретный токен. Этим же значением аутентифицируются события, которые Битрикс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) — результат одинаковый.

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

• Получить бота
• Зарегистрировать бота
• Бот-платформа
• Лимиты и оптимизация