Перенос владения ботом

POST /v1/bots/:botId/transfer

Переносит владение ботом на другой API-ключ того же аккаунта Битрикс24 и того же пользователя (или администратора аккаунта). Решает ситуацию, когда бот «осиротел» после пересоздания приложения: ключ-владелец отозван, и рантайм бота переставал работать. Перенос меняет только привязку ключа — botId, история чатов и подписки сохраняются. B24-вызов не выполняется; после переноса проверьте B24-привязку нового ключа через `POST /v1/bots/:botId/reauth`.

Параметры

Параметр Тип Обяз. Описание
botId number да ID бота (path-параметр)
targetApiKeyId string да ID целевого API-ключа (тело запроса)

Целевой ключ должен быть активен (ACTIVE), в том же аккаунте, что и бот, принадлежать тому же пользователю (или вызов делает администратор аккаунта), иметь область imbot и не быть служебным платформенным ключом (cowork, агент-сит, agent-maintenance) — у таких ключей жизненный цикл управляется платформой, бот снова «осиротеет» при их ротации.

Примеры

curl

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/bots/42/transfer \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targetApiKeyId": "ck_target_key_id" }'

JavaScript

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/bots/42/transfer', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ targetApiKeyId: 'ck_target_key_id' }),
})
const { data } = await res.json()
console.log(data) // { transferred: true, botId: 42, fromApiKeyId: '...', toApiKeyId: '...' }

Поля ответа

Поле Тип Описание
data.transferred boolean true, если привязка изменилась; false — если ключ уже был владельцем (идемпотентный no-op)
data.botId number ID бота
data.fromApiKeyId string ID прежнего ключа-владельца (только при transferred: true)
data.toApiKeyId string ID нового ключа-владельца

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

JSON 
{
  "success": true,
  "data": {
    "transferred": true,
    "botId": 42,
    "fromApiKeyId": "ck_old_owner",
    "toApiKeyId": "ck_target_key_id"
  }
}

Если целевой ключ уже владеет ботом, перенос не выполняется и возвращается transferred: false (при этом fromApiKeyId равен toApiKeyId — текущему владельцу).

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

400 — целевой ключ не подходит (с уточнением в поле reason):

JSON 
{
  "success": false,
  "error": {
    "code": "TARGET_KEY_INVALID",
    "message": "Target API key is not eligible to own this bot.",
    "reason": "wrong_user"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_BOT_ID botId не является числом
400 INVALID_PARAMS Не передан targetApiKeyId или он не строка
400 TARGET_KEY_INVALID Целевой ключ не подходит. reason: not_active · wrong_portal · wrong_user · missing_scope · expired · system_key (служебный платформенный ключ)
403 NOT_BOT_OWNER Вызывающий не владеет ботом (нужен тот же пользователь, что у ключа-владельца, или администратор аккаунта)
403 SCOPE_DENIED API-ключ не имеет области imbot
403 WRITE_BLOCKED_READONLY_KEY Ключ в режиме «только чтение»
404 BOT_NOT_FOUND Бот не найден в аккаунте
404 TARGET_KEY_NOT_FOUND Целевой ключ не найден
409 BOT_TRANSFER_NOT_ALLOWED Бот управляется агентом или управляемым ботом — переносите через соответствующий ресурс, а не напрямую
409 BOT_TRANSFER_CONFLICT Владение изменилось параллельным запросом — перечитайте текущего владельца и повторите при необходимости

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

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

Когда применять. Бот перестал работать после пересоздания OAuth-приложения: ключ-владелец отозван, и рантайм бота больше не запускается. Перенос на активный личный ключ (vibe_api_*) того же аккаунта восстанавливает работу бота — рантайм не зависит от того, каким приложением был зарегистрирован бот.

Авторизация по пользователю, а не по ключу. Перенос разрешён владельцу бота (тому же пользователю Vibe, что и у текущего ключа-владельца — даже если ключ уже отозван) или администратору аккаунта. Держать текущий ключ-владелец не требуется — именно поэтому перенос работает, когда исходный ключ отозван.

Идемпотентность. Перенос на текущий ключ-владелец (в том числе отозванный) — безопасный no-op: возвращается transferred: false, привязка не меняется, запись в журнал не создаётся.

Проверка после переноса. B24-вызов при переносе не выполняется. Чтобы убедиться, что новый ключ может управлять ботом, вызовите `POST /v1/bots/:botId/reauth` — он проверит B24-привязку нового ключа.

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