## Re-subscribe to events

`POST /v1/bots/:botId/resubscribe`

Restores the bot's subscription to Bitrix24 events. Use it when the bot is active but `GET /v1/bots/:botId/events` has stopped returning events. No request body is required.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `botId` | number | yes | Bot ID (path parameter) |

## Examples

### curl — personal key

```bash
curl -X POST https://vibecode.bitrix24.com/v1/bots/42/resubscribe \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -X POST https://vibecode.bitrix24.com/v1/bots/42/resubscribe \
  -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/42/resubscribe', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log(data) // { resubscribed: true, eventMode: 'fetch', b24EventMode: 'fetch', diverged: false, hint: '…' }
```

### JavaScript — OAuth application

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

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | Re-subscription result |
| `data.resubscribed` | boolean | `true` on successful re-subscription |
| `data.eventMode` | string | The event delivery mode stored by the platform: `fetch` or `webhook` |
| `data.b24EventMode` | string \| null | The delivery mode configured for the bot in Bitrix24 before the call: `fetch` or `webhook`. `null` means the Bitrix24 account did not report it |
| `data.diverged` | boolean | `true` when the mode in Bitrix24 differed from the stored one and the call aligned it. `false` when `b24EventMode` is `null` |
| `data.hint` | string | What the call did and what to check next |

## Response example

```json
{
  "success": true,
  "data": {
    "resubscribed": true,
    "eventMode": "fetch",
    "b24EventMode": "fetch",
    "diverged": false,
    "hint": "Bitrix24 already had eventMode='fetch' for this bot, so this call rewrote the same value and did no subscription work — Bitrix24 rebinds only when the mode actually changes. A fetch-mode bot receives events only while Bitrix24's own eventMode is 'fetch', and b_rest_event subscriptions play no part in polling (they are a webhook-mode mechanism). If GET /v1/bots/42/events still returns an empty queue, the cause is upstream of the queue: confirm the bot is a participant of the chat where messages are sent, and that a mention-only (type='personal') bot is actually being mentioned."
  }
}
```

## Error response example

409 — another change to the bot is still being reconciled with Bitrix24; the response carries the `Retry-After: 30` header:

```json
{
  "success": false,
  "error": {
    "code": "BOT_EFFECT_IN_PROGRESS",
    "message": "Another change to this bot is still being reconciled with Bitrix24",
    "retryAfter": 30
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_BOT_ID` | `botId` is not a number |
| 404 | `BOT_NOT_FOUND` | Bot not found |
| 409 | `BOT_RECOVERY_IN_PROGRESS` | The portal address changed after the bot was registered and the registration is being recovered. Nothing is sent to Bitrix24. Retry after the delay in the `Retry-After: 5` header |
| 409 | `BOT_EFFECT_IN_PROGRESS` | Another change to the bot is still being reconciled with Bitrix24. Retry after the delay specified in the `Retry-After` header: 30 seconds, or, if the change is awaiting the next scheduled check, the time until that check (up to 300 seconds) |
| 409 | `BOT_UNAVAILABLE` | The bot's state must be repaired on the platform side. There is no `Retry-After` header and retrying will not help. Contact support and quote the request time |
| 409 | `BOT_ID_REPLACED` | The request uses a previous bot ID. Use the current ID from `error.details.botId`. No `Retry-After` header |
| 409 | `BOT_OAUTH_POLICY_INVALID` | The stored settings are incompatible with OAuth application ownership of the bot. No `Retry-After` header |
| 409 | `BOT_APP_EVENT_ENROLLMENT_REQUIRED` | The platform receiver requires a recent, verified INSTALL/placement of the bound application. No `Retry-After` header |
| 409 | `BOT_APP_EVENT_CONSUMER_REQUIRED` | The platform receiver requires a verified Agent or ManagedBot owner. No `Retry-After` header |
| 409 | `BOT_APP_EVENT_CREDENTIAL_CHANGED` | The application-event binding changed between admission and dispatch. Verify the application enrollment again before retrying. No `Retry-After` header |
| 403 | `BOT_ACCESS_DENIED` | The bot belongs to a different API key |
| 403 | `SCOPE_DENIED` | The API key does not have the `imbot` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only — see [access rights](/docs/access-rights) |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**When to use.** The bot is registered and active — messages arrive in chats and the bot appears in the `GET /v1/bots` list — but the event queue stays empty. A `hint` field in the `GET /v1/bots/:botId/events` response confirms the diagnosis, but its absence does not make the call unnecessary: the hint only shows up once the queue has stayed persistently empty. Re-subscription preserves the Open Channels and welcome-bot bindings, unlike re-registration via `POST /v1/bots`.

**What the call actually repairs.** Only aligning the mode restores delivery: `diverged: true` means the mode in Bitrix24 differed from the stored one and now matches it. With `diverged: false` and equal `b24EventMode` and `eventMode`, the call wrote the same value and did not change the event subscription. In that case, use the `hint` to find the cause of the empty queue: check whether the bot is in the chat and whether a `personal` bot is actually being mentioned. If the platform's stored mode is `webhook` and Bitrix24's mode was `fetch`, switching modes deletes unread events from the queue: retrieve them through `GET /v1/bots/:botId/events` before making the call.

**Repeated calls are safe.** Each request re-sends the bot's delivery mode to Bitrix24, so you can re-subscribe several times in a row.

**Bitrix24 account address change.** If the Bitrix24 account address changed after the bot was registered, the platform recovers the bot's registration and Open Channels bindings by itself. Until it finishes, event polling and every call that changes the bot, including re-subscription and deletion through `DELETE /v1/bots/:botId`, return `409 BOT_RECOVERY_IN_PROGRESS`. Contact support if the recovery does not finish.

An address change made before this diagnostic became available does not produce a `409`. If the address changed and re-subscription did not restore delivery: for a standalone Bot, delete the old registration through `DELETE /v1/bots/:botId` before reusing the same `code`, or register a new unique `code`, then restore the Open Channels and `WELCOME_BOT` bindings. The same code may reuse the old identity and does not guarantee a new bot ID. For a bot owned by an AI agent or a managed bot, do not call `DELETE /v1/bots/:botId`: use the owner resource's recovery lifecycle, or contact support if that recovery is unavailable.

**`webhook` mode.** For a bot with `eventMode: "webhook"`, re-subscription also re-sends the stored webhook address.

## See also

- [Events](/docs/bots/events)
- [Troubleshooting](/docs/bots/troubleshooting)
- [Bot re-authorization](/docs/bots/management/reauth)