Для AI-агентов: markdown этой страницы — /docs-content/bots/management/update.md индекс документации — /llms.txt

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

Новые OAuth-боты поддерживают fetch и webhook. Платформа подтверждает владение ботом через то же OAuth-приложение и точные id/code, без передачи botToken в OAuth API. Для доставки на /api/bot/webhook нужен свежий проверенный INSTALL/placement связанного приложения; иначе регистрация возвращает 409 BOT_APP_EVENT_ENROLLMENT_REQUIRED. Исторический токен приложения не заменяет эту проверку. События до завершения первой регистрации удерживаются в зашифрованной ограниченной очереди. Смена botToken нового application-owned бота запрещена (409 BOT_OAUTH_POLICY_INVALID); unmarked legacy-боты автоматически не преобразуются. Самостоятельный OAuth-ключ без связанного приложения может использовать fetch или собственный receiver, но не получает доверия приёмника платформы.

Приёмник платформы доступен ботам Agent и ManagedBot с подтверждённым владельцем. Бот приложения без такого владельца получает 409 BOT_APP_EVENT_CONSUMER_REQUIRED до записи в Битрикс24. Для него остаются fetch и собственный callback. События уже опубликованного бота после смены адреса портала могут храниться в зашифрованном карантине до подтверждения и публикации восстановленной идентичности. Доставка возможна только при неизменной callback-привязке, сохранении допуска приложения и членства автора в портале, а также подтверждении права доставки восстановленных событий. При смене или невозможности подтвердить эти основания события отбрасываются безвозвратно, а восстановление идентичности бота продолжается. Ограниченный срок хранения не гарантирует доставку. На одно восстановление допускается не более 256 событий и 4 МиБ ciphertext, срок хранения — 72 часа. Повтор события не продлевает срок. При переполнении приёмник возвращает 503 без подтверждения приёма.

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)

Параметр (плоский) Параметр (формат Битрикс24) Тип Описание
Параметр (плоский)name Параметр (формат Битрикс24)fields.properties.name Типstring ОписаниеНовое имя бота, не более 50 кодовых точек Unicode. Более длинное имя отклоняется до изменения, без усечения. Ограничение проверяется для фактически передаваемого имени, включая алиасы PROPERTIES и NAME; при наличии обёртки проигнорированное плоское имя не проверяется
Параметр (плоский)lastName Параметр (формат Битрикс24)fields.properties.lastName Типstring ОписаниеНовая фамилия
Параметр (плоский)workPosition Параметр (формат Битрикс24)fields.properties.workPosition Типstring ОписаниеНовая должность
Параметр (плоский)color Параметр (формат Битрикс24)fields.properties.color Типstring ОписаниеНовый цвет аватара
Параметр (плоский)gender Параметр (формат Битрикс24)fields.properties.gender Типstring ОписаниеПол: M или F
Параметр (плоский)avatar Параметр (формат Битрикс24)fields.properties.avatar Типstring ОписаниеАватар бота: PNG или JPEG как base64-строка без префикса data:image/...;base64,, до ~50 КБ. См. «Известные особенности»
Параметр (плоский)eventMode Параметр (формат Битрикс24)fields.eventMode Типstring ОписаниеРежим событий: fetch или webhook
Параметр (плоский)webhookUrl Параметр (формат Битрикс24)fields.webhookUrl Типstring ОписаниеURL для push-уведомлений
Параметр (плоский)isHidden Параметр (формат Битрикс24)fields.isHidden Типboolean ОписаниеСкрыть из списка контактов
Параметр (плоский)isReactionsEnabled Параметр (формат Битрикс24)fields.isReactionsEnabled Типboolean ОписаниеРазрешить реакции
Параметр (плоский)backgroundId Параметр (формат Битрикс24)fields.backgroundId Типstring ОписаниеФон чата: azure, mint, steel, slate, teal, cornflower, sky, peach, frost
Параметр (плоский)isSupportOpenline Параметр (формат Битрикс24)fields.isSupportOpenline Типboolean ОписаниеПоддержка открытых линий (только для type: "openline")
Параметр (плоский)— Параметр (формат Битрикс24)fields.botToken Типstring ОписаниеДля ботов с личным ключом и OAuth-ботов, зарегистрированных по прежней схеме. Новые OAuth-боты с владением приложением отклоняют это поле с 409 BOT_OAUTH_POLICY_INVALID. Свой токен бота вместо выданного платформой. В событиях приходит custom с этим значением (см. Проверка вебхука). От 32 до 40 символов из алфавита [A-Za-z0-9_-]. Значение вне этих границ отклоняется с 400 BOT_TOKEN_INVALID до вызова портала, и токен бота не меняется. Принимается только в форме с fields — плоского имени у поля нет. См. «Известные особенности»
Параметр (плоский)disabled Параметр (формат Битрикс24)— Типboolean ОписаниеВозвращает в работу бота, отключённого платформой. Принимается только в плоской форме и только как false — имени в fields у поля нет, потому что его применяет платформа и в Битрикс24 оно не уходит. Это единственное поле, которое работает на отключённом боте: запрос отвечает до проверки BOT_DISABLED — 200 и тело {"success": true, "data": {"id": "<строковый id записи бота>", "disabled": false}} (без bot и без users). disabled: true отклоняется с 400 DISABLE_NOT_ALLOWED. См. «Известные особенности»

Примеры

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 Код Описание
HTTP400 КодINVALID_BOT_ID ОписаниеbotId не является числом
HTTP400 КодBOT_NAME_TOO_LONG ОписаниеФактически передаваемое имя длиннее 50 кодовых точек Unicode. Обновление не выполняется, имя и остальные свойства остаются прежними; передайте более короткое имя
HTTP400 КодBOT_TOKEN_INVALID Описаниеfields.botToken короче 32 или длиннее 40 символов, содержит символы вне [A-Za-z0-9_-] либо передан не строкой. Портал не вызывается, токен бота остаётся прежним
HTTP400 КодDISABLE_NOT_ALLOWED ОписаниеВ теле передан disabled: true. Отключение принадлежит системе и запросить его нельзя: чтобы убрать бота, используйте DELETE /v1/bots/:botId
HTTP404 КодBOT_NOT_FOUND ОписаниеБот не найден
HTTP403 КодBOT_ACCESS_DENIED ОписаниеБот принадлежит другому API-ключу
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа imbot
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч только для чтения — см. права доступа
HTTP409 КодBOT_RECOVERY_IN_PROGRESS ОписаниеАвтоматическое восстановление после смены адреса портала. Дождитесь Retry-After: 5.
HTTP409 КодBOT_EFFECT_IN_PROGRESS ОписаниеДругое изменение бота согласуется. Дождитесь Retry-After: 30 секунд либо 1–300 до плановой проверки.
HTTP409 КодBOT_UNAVAILABLE ОписаниеСостояние бота требует исправления поддержкой. Retry-After отсутствует; остановите автоматические повторы и обратитесь в поддержку.
HTTP409 КодBOT_ID_REPLACED ОписаниеПрежний ID бота заменён. Используйте текущий ID из error.details.botId. Retry-After отсутствует.
HTTP409 КодBOT_REGISTRATION_CONTEXT_CHANGED ОписаниеТолько при возврате плоским disabled: false: lifecycle или владелец изменились параллельно. Retry-After отсутствует; перечитайте бота перед повтором.
HTTP409 КодBOT_OAUTH_POLICY_INVALID ОписаниеИзменение противоречит владению ботом OAuth-приложением, в том числе попытка сменить botToken нового OAuth-бота
HTTP409 КодBOT_APP_EVENT_ENROLLMENT_REQUIRED ОписаниеДля приёмника платформы нужен свежий проверенный INSTALL/placement связанного приложения
HTTP409 КодBOT_APP_EVENT_CONSUMER_REQUIRED ОписаниеДля приёмника платформы требуется подтверждённый владелец Agent или ManagedBot. Используйте ключ владельца либо выберите fetch или собственный приёмник
HTTP410 КодBOT_DISABLED ОписаниеБот отключён и не обрабатывает вызовы API. Исключение: плоское тело {"disabled": false} — это путь возврата бота, он обрабатывается до этой проверки и отвечает 200. Любое другое тело на отключённом боте получает эту ошибку, включая форму disabled внутри fields. Как вернуть бота — Бот отключён
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов
HTTP422 КодAPP_HOST_NOT_ALLOWED_HERE ОписаниеwebhookUrl указывает на адрес с именем в домене приложений платформы (<имя>.<домен>, а не app-…), и это имя не закреплено за сервером вашего аккаунта Битрикс24. Ничего не сохраняется, Битрикс24 не вызывается. Имя вашего сервера принимается и сохраняется как адрес app-… этого сервера

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

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

Формат тела запроса. Как и POST /v1/bots, PATCH принимает плоское тело ({ name, eventMode, ... }). Можно передать и вложенную структуру fields в формате Битрикс24. В начале страницы описано, как платформа определяет вложенную структуру и когда преобразует плоское тело.

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

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

Terminal
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}'
JSON
{ "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 ещё и проверяет доступ.

Следующие рекомендации по токену относятся к ботам с личным ключом и OAuth-ботам, зарегистрированным по прежней схеме.

Задайте свой токен бота, если вашему приёмнику нужно известное значение для проверки. Платформа создаёт токен при регистрации и не возвращает его в ответах API. Для ботов с личным ключом и OAuth-ботов, зарегистрированных по прежней схеме, Битрикс24 присылает custom с токеном бота в auth.application_token. См. Проверка вебхука. Берите случайное значение длиной от 32 до 40 символов, например 32 шестнадцатеричных символа. Осмысленные строки вроде support-bot-2026 этим требованиям не соответствуют. Новые OAuth-боты приложения используют токен приложения и отклоняют fields.botToken с 409 BOT_OAUTH_POLICY_INVALID.

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

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