Для AI-агентов: markdown этой страницы — /docs-content/bots/management/resubscribe.md индекс документации — /llms.txt
Перепривязка подписки на события
POST /v1/bots/:botId/resubscribe
Восстанавливает подписку бота на события Битрикс24. Применяется, когда бот активен, но GET /v1/bots/:botId/events перестал возвращать события. Тело запроса не требуется.
Параметры
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
ПараметрbotId |
Типnumber | Обяз.да | ОписаниеID бота (path-параметр) |
Примеры
curl — личный ключ
curl -X POST https://vibecode.bitrix24.tech/v1/bots/42/resubscribe \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl -X POST https://vibecode.bitrix24.tech/v1/bots/42/resubscribe \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/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-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/bots/42/resubscribe', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
},
})
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata |
Типobject | ОписаниеРезультат перепривязки |
Полеdata.resubscribed |
Типboolean | Описаниеtrue при успешной перепривязке |
Полеdata.eventMode |
Типstring | ОписаниеРежим доставки событий, сохранённый на платформе: fetch или webhook |
Полеdata.b24EventMode |
Типstring | null | ОписаниеРежим доставки, который Битрикс24 держал для бота до вызова: fetch или webhook. null — портал не сообщил режим |
Полеdata.diverged |
Типboolean | Описаниеtrue, если режим в Битрикс24 расходился с сохранённым и вызов его выровнял. При b24EventMode: null — false |
Полеdata.hint |
Типstring | ОписаниеЧто сделал вызов и что проверить дальше |
Пример ответа
{
"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."
}
}
Пример ответа при ошибке
409 — другое изменение бота ещё сверяется с Битрикс24, ответ несёт заголовок Retry-After: 30:
{
"success": false,
"error": {
"code": "BOT_EFFECT_IN_PROGRESS",
"message": "Another change to this bot is still being reconciled with Bitrix24",
"retryAfter": 30
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодINVALID_BOT_ID |
ОписаниеbotId не является числом |
| HTTP404 | КодBOT_NOT_FOUND |
ОписаниеБот не найден |
| HTTP409 | КодBOT_RECOVERY_IN_PROGRESS |
ОписаниеАдрес портала сменился после регистрации бота, идёт восстановление регистрации. Вызов в Битрикс24 не отправляется. Повторите после паузы из заголовка Retry-After: 5 |
| HTTP409 | КодBOT_EFFECT_IN_PROGRESS |
ОписаниеДругое изменение бота ещё сверяется с Битрикс24. Повторите после паузы из заголовка Retry-After: 30 секунд, а если изменение ждёт следующей плановой сверки — время до неё, не больше 300 секунд |
| HTTP409 | КодBOT_UNAVAILABLE |
ОписаниеСостояние бота требует исправления на стороне платформы. Заголовка Retry-After нет, повтор не поможет. Обратитесь в поддержку и укажите время запроса |
| HTTP409 | КодBOT_ID_REPLACED |
ОписаниеВ запросе указан прежний ID бота. Используйте актуальный ID из error.details.botId. Заголовка Retry-After нет |
| HTTP409 | КодBOT_OAUTH_POLICY_INVALID |
ОписаниеСохранённые настройки несовместимы с владением ботом через OAuth-приложение. Заголовка Retry-After нет |
| HTTP409 | КодBOT_APP_EVENT_ENROLLMENT_REQUIRED |
ОписаниеДля приёмника платформы нужен свежий подтверждённый INSTALL/placement связанного приложения. Заголовка Retry-After нет |
| HTTP409 | КодBOT_APP_EVENT_CONSUMER_REQUIRED |
ОписаниеДля приёмника платформы нужен подтверждённый владелец Agent или ManagedBot. Заголовка Retry-After нет |
| HTTP409 | КодBOT_APP_EVENT_CREDENTIAL_CHANGED |
ОписаниеПривязка событий приложения изменилась между допуском и отправкой запроса. Подтвердите подключение приложения заново перед повтором. Заголовка Retry-After нет |
| HTTP403 | КодBOT_ACCESS_DENIED |
ОписаниеБот принадлежит другому API-ключу |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеAPI-ключ не имеет скоупа imbot |
| HTTP403 | КодWRITE_BLOCKED_READONLY_KEY |
ОписаниеКлюч только для чтения — см. права доступа |
| HTTP401 | КодTOKEN_MISSING |
ОписаниеAPI-ключ не имеет настроенных токенов |
Полный список общих ошибок API — Ошибки.
Известные особенности
Когда применять. Бот зарегистрирован и активен — в чаты приходят сообщения, бот есть в списке GET /v1/bots — но очередь событий остаётся пустой. Появившееся в ответе GET /v1/bots/:botId/events поле hint подтверждает диагноз, а его отсутствие вызов не отменяет: подсказка приходит только при устойчиво пустой очереди. Перепривязка сохраняет привязки открытых линий и приветственного бота, в отличие от повторной регистрации через POST /v1/bots.
Что именно чинит вызов. Доставку восстанавливает только выравнивание режима: ответ с diverged: true означает, что режим в Битрикс24 расходился с сохранённым и теперь совпадает. При diverged: false и равных b24EventMode и eventMode вызов записал то же значение и подписку не менял. Причину пустой очереди тогда ищите по подсказке hint: участвует ли бот в чате, упоминают ли бота с типом personal. Если на платформе сохранён режим webhook, а в Битрикс24 был fetch, переключение удаляет непрочитанные события очереди: заберите их через GET /v1/bots/:botId/events до вызова.
Повторный вызов безопасен. Каждый запрос заново отправляет режим доставки бота в Битрикс24, поэтому перепривязку можно вызывать несколько раз подряд.
Смена адреса портала. Если адрес портала сменился после регистрации бота, платформа сама восстанавливает регистрацию бота и привязки открытых линий. До завершения опрос событий и любые вызовы, изменяющие бота, включая перепривязку и удаление через DELETE /v1/bots/:botId, отвечают 409 BOT_RECOVERY_IN_PROGRESS. Если восстановление не завершается, обратитесь в поддержку.
Смена адреса до появления этой диагностики отказом 409 не сопровождается. Если адрес менялся, а перепривязка не вернула доставку, для самостоятельного Bot удалите прежнюю регистрацию через DELETE /v1/bots/:botId перед повторным использованием того же code либо зарегистрируйте новый уникальный code, затем восстановите привязки открытых линий и WELCOME_BOT. Тот же код может переиспользовать прежнюю идентичность и не гарантирует новый ID бота. Для бота, принадлежащего AI-агенту или управляемому боту, не вызывайте DELETE /v1/bots/:botId: используйте восстановление ресурса-владельца, а если оно недоступно — обратитесь в поддержку.
Режим webhook. Для бота с eventMode: "webhook" перепривязка также повторно отправляет сохранённый адрес вебхука.