Восстановление доступа к боту

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

Как выглядит потеря доступа

Признаки приходят все сразу:

• GET /v1/bots отвечает успехом и пустым массивом bots, хотя бот на портале работает.
• POST /v1/bots с тем же code отвечает 409 BOT_ALREADY_EXISTS — код занят.
• GET /v1/bots/:botId по идентификатору из ответа 409 отвечает 403 BOT_ACCESS_DENIED.
• GET /v1/me при этом подтверждает, что сам ключ действует: accessMode равен READWRITE, скоуп imbot присутствует.

Список ботов ключом, который ими не управляет:

{
  "success": true,
  "data": {
    "bots": [],
    "users": [],
    "hasNextPage": false
  }
}

Повторная регистрация с тем же кодом — в поле data приходит существующий бот:

{
  "success": false,
  "error": {
    "code": "BOT_ALREADY_EXISTS",
    "message": "Bot with this code already exists"
  },
  "data": {
    "botId": 42,
    "code": "support_bot",
    "name": "Техподдержка"
  }
}

Обращение к этому боту тем же ключом:

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

Почему бот не виден

У бота две разные привязки. Владение закреплено за пользователем Вайбкод и не меняется, когда ключи истекают или отзываются. Привязка к ключу означает другое — каким ключом бот управляется сейчас.

GET /v1/bots возвращает записи из базы Вайбкод, отфильтрованные по вызывающему ключу, поэтому бот, зарегистрированный другим ключом, в список не попадает. Остальные операции — события, сообщения, обновление — авторизуются так же и отвечают 403 BOT_ACCESS_DENIED.

Уникальность кода бота при этом проверяется в границах портала, а не ключа. Отсюда и расхождение: список пуст, а код занят.

Сам бот не затронут. Он остаётся на портале, состоит в тех же чатах и сохраняет историю сообщений — недоступно только управление им через API.

Как вернуть доступ

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

1. Узнать идентификатор бота

Повторите регистрацию с тем же code. Ответ 409 означает, что код занят: идентификатор существующего бота приходит в data.botId, и запись бота при этом не меняется. Регистрация выполняется от лица администратора портала Битрикс24 — иначе Битрикс24 отвечает отказом в доступе.

curl -X POST https://vibecode.bitrix24.tech/v1/bots \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "support_bot", "name": "Техподдержка" }'

Ответ 201 вместо 409 означает, что регистрация прошла идемпотентно. Владение при этом не переходит, бот по-прежнему не приходит в GET /v1/bots, а его name, type, eventMode и webhookUrl обновляются значениями из запроса. Если бот работал в режиме webhook, передайте eventMode и webhookUrl вместе с code и name, чтобы сохранить доставку событий. Идентификатор бота в этом ответе приходит в data.botId — переходите к шагу 2.

Порядок применим к ботам, зарегистрированным через Вайбкод. Бот, заведённый на портале Битрикс24 в обход платформы, в базе Вайбкод записи не имеет: в ответе 409 поле data не придёт, а перенос ответит 404 BOT_NOT_FOUND.

2. Узнать идентификатор целевого ключа

targetApiKeyId — это поле id записи ключа, а не строка ключа. Список отдаёт GET /v1/keys менеджмент-ключу со скоупом vibe:mgmt:keys — ключу портала этот список не доступен, в ответ приходит 401 WRONG_KEY_TYPE. Менеджмент-ключ создаётся в личном кабинете, и для этого шага достаточно ключа в режиме «только чтение»: список отдаётся, а изменять ключи такой ключ не может. После переноса его можно отозвать.

В ответ приходят ключи владельца менеджмент-ключа на указанном портале. Свой ключ узнаётся по полям prefix и suffix, portalId приходит в поле portal.id ответа GET /v1/me — этому вызову менеджмент-скоупы не нужны. Тот же идентификатор отдаёт GET /v1/portals, но у него свой скоуп vibe:mgmt:portals. Администратору, который переносит бота на ключ другого пользователя, идентификатор этого ключа сообщает его владелец — чужие ключи в списке не приходят.

curl -H "X-Api-Key: YOUR_MANAGEMENT_KEY" \
  "https://vibecode.bitrix24.tech/v1/keys?portalId=PORTAL_ID"

3. Перенести владение

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" }'

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

После этого ответа бот приходит в GET /v1/bots нового ключа.

4. Проверить привязку

Перенос меняет привязку на стороне Вайбкод. Проверяет доступ нового ключа к боту на портале отдельный вызов. Он отвечает только ключу-владельцу, поэтому шаг выполняет владелец целевого ключа: администратор, перенёсший бота на ключ другого пользователя, получит 403 BOT_ACCESS_DENIED.

curl -X POST https://vibecode.bitrix24.tech/v1/bots/42/reauth \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "validated": true,
    "refreshed": false
  }
}

validated: true подтверждает, что новый ключ управляет ботом на портале, — с ним снова работают события, сообщения и обновление.

Требования к целевому ключу

Ключ принимается, когда выполнены все условия:

Режим доступа целевого ключа перенос не проверяет — ключ «только чтение» он примет. Управлять ботом таким ключом всё равно нельзя: шаг 4 и все последующие вызовы ответят 403 WRITE_BLOCKED_READONLY_KEY. Переносите владение на ключ в режиме READWRITE.

Проверить ключ до вызова можно по его записи из GET /v1/keys шага 2: состояние приходит в поле status, портал — в portalId, владелец — в userId, скоупы — в scopes, срок действия — в expiresAt, режим доступа — в accessMode.

Ключ, не прошедший проверку, отклоняется с 400 TARGET_KEY_INVALID, а причина приходит в поле reason — расшифровка причин в таблице ошибок раздела Перенос владения ботом.

Когда это нужно

Три состояния приводят к одной картине — бот работает, а ключ его не видит.

Ключ-владелец перестал работать. Значение ключа не сохранили при создании, ключ отозван или его срок действия закончился. Привязка бота цела — доступ возвращается переносом на новый ключ.

Бот зарегистрирован другим ключом. Так происходит, когда приложение развёрнуто с одним ключом, а бот регистрировался другим, либо когда ключ пересоздали вместе с OAuth-приложением. Перенос собирает бота и рабочий ключ обратно вместе.

Бот принадлежит ресурсу платформы. Ботом AI-агента или управляемого бота распоряжается сам ресурс, поэтому прямой перенос отвечает 409 BOT_TRANSFER_NOT_ALLOWED. Такой бот восстанавливается со стороны своего ресурса — см. AI-агенты.

Ошибки

Полный справочник кодов — Коды ошибок.

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

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

Прежний ключ перестаёт видеть бота сразу. После переноса бот пропадает из GET /v1/bots прежнего ключа — остальные его боты в списке остаются. Если бота опрашивали два процесса, опрос продолжает только тот, что работает новым ключом.

Регистрация под новым кодом даёт другого бота. У него собственный botId, собственные чаты и история, а прежний бот остаётся на портале и продолжает занимать свой код.

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

• Перенос владения ботом
• Повторная авторизация бота
• Список ботов
• Диагностика проблем
• Менеджмент-ключи