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 registration that was already sent 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 DescriptionThe registration result is not confirmed yet. Repeat the call after the number of seconds in the Retry-After header. If the response persists, contact support and provide error.details.registrationRef
HTTP409 CodeBOT_REGISTRATION_AMBIGUOUS DescriptionThe key started several unfinished registrations with this code. If the response persists, contact support and provide the bot code and the Bitrix24 account
HTTP409 Codepending reason code DescriptionThe registration is waiting for reconciliation with Bitrix24, and the reason is in error.code. Repeat the call after the number of seconds in Retry-After: 5 seconds or the time until the next scheduled registration check. If the response persists, contact support and provide error.details.registrationRef when the response contains it
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