Для 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 — личный ключ

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

curl — OAuth-приложение

Terminal
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 — личный ключ

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-приложение

javascript
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 ОписаниеЧто сделал вызов и что проверить дальше

Пример ответа

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

Пример ответа при ошибке

409 — другое изменение бота ещё сверяется с Битрикс24, ответ несёт заголовок Retry-After: 30:

JSON
{
  "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" перепривязка также повторно отправляет сохранённый адрес вебхука.

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