Для 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 — личный ключ
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',
},
}),
})
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
Поле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 | ОписаниеКарточка бота как пользователя портала |
Пример ответа
Показаны основные поля. Полный набор полей бота — в ответе регистрации.
{
"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"
}
}
Ошибки
| 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 не вызывает:
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 ещё и проверяет доступ.
Следующие рекомендации по токену относятся к ботам с личным ключом и 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) — результат одинаковый.