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

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

POST /v1/bots/:botId/transfer

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

Параметры

Параметр Тип Обяз. Описание
botId (path) number да ID бота. Список: GET /v1/bots. Если бота там нет, его ID приходит в поле data.botId ответа 409 BOT_ALREADY_EXISTS — см. Восстановление доступа к боту

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

Поле Тип Обяз. Описание
targetApiKeyId string да Идентификатор записи целевого ключа, поле id в ответе GET /v1/keys. Не строка ключа

Целевой ключ должен быть активным ключом общего назначения того же портала, со скоупом imbot и незакончившимся сроком действия, и принадлежать тому же пользователю Вайбкод, который выполняет перенос. Администратор портала переносит бота на ключ любого пользователя того же портала. Ключ, не прошедший проверку, отклоняется с 400 TARGET_KEY_INVALID, конкретная причина приходит в поле reason — расшифровка причин в таблице Ошибки.

Примеры

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": "3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33" }'

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: '3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33' }),
})
const { data } = await res.json()
console.log(data) // { transferred: true, botId: 42, fromApiKeyId: '...', toApiKeyId: '...' }

Поля ответа

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

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

JSON 
{
  "success": true,
  "data": {
    "transferred": true,
    "botId": 42,
    "fromApiKeyId": "8c41d5e7-2b90-4a63-b1f5-6d7e9a0c4b12",
    "toApiKeyId": "3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33"
  }
}

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

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 — Ошибки.

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

Работа бота не зависит от приложения-регистратора. Перенос на активный личный ключ vibe_api_* того же портала восстанавливает работу бота независимо от того, каким приложением он был зарегистрирован. Полный порядок с поиском botId и идентификатора целевого ключа — Восстановление доступа к боту.

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

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

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