For AI agents: markdown of this page — /docs-content-en/bots/management/registrations-recover.md documentation index — /llms.txt

Recover a bot registration

POST /v1/bots/registrations/:code/recover

Completes a bot registration whose result was not confirmed right away and returns the bot ID in the Bitrix24 account. Call it with the same key and the same bot code as the original registration.

The call is needed when POST /v1/bots responded with 409 BOT_EFFECT_DESIRED_STATE_NOT_PROVED: the registration request was sent, but its result has not been checked yet. No new bot is registered — Vibecode checks the previously submitted registration and completes the bot record.

Parameters

Parameter Type Required Description
Parametercode (path) Typestring Requiredyes DescriptionBot code — the value of the code field from the POST /v1/bots request

No request body is required.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/registrations/support_bot/recover \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/registrations/support_bot/recover \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/registrations/support_bot/recover', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log(data) // { botId: 42, code: 'support_bot', recovered: true }

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/registrations/support_bot/recover', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

Field Type Description
Fielddata.botId Typenumber DescriptionBot ID in the Bitrix24 account — the same as data.bots[].id in GET /v1/bots
Fielddata.code Typestring DescriptionBot code from the request path
Fielddata.recovered Typeboolean DescriptionAlways true

Response example

JSON 
{
  "success": true,
  "data": {
    "botId": 42,
    "code": "support_bot",
    "recovered": true
  }
}

Error response example

404 — the key has no registration with this code:

JSON 
{
  "success": false,
  "error": {
    "code": "BOT_REGISTRATION_NOT_FOUND",
    "message": "No owned registration is available for recovery"
  }
}

Errors

HTTP Code Description
HTTP400 CodeCODE_REQUIRED DescriptionThe bot code in the path is empty
HTTP404 CodeBOT_REGISTRATION_NOT_FOUND DescriptionThe key has no registration with this code that can be completed. A call with a key or code other than the ones used at registration gets the same response
HTTP409 CodeBOT_REGISTRATION_RECOVERY_PENDING DescriptionRegistration confirmation or reconciliation is still pending. The Retry-After header gives the retry delay in seconds: the time until the next scheduled check (1 to 300 seconds), or 30 seconds otherwise. If the response persists, contact support and provide error.details.registrationRef when present
HTTP409 CodeBOT_UNAVAILABLE DescriptionThe registration state requires a fix by the platform, for example due to an incompatible OAuth policy or a change in application enrollment. There is no Retry-After header and retrying will not help. Contact support with error.details.registrationRef when present, otherwise the original bot code and Bitrix24 account
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the imbot scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — see access rights

Full list of common API errors — Errors.

Known specifics

Repeating the call is safe. If the registration is already completed, a call with the same key and code returns 200 with the same botId again.

See also