SMeet Bot API

Эксплуатация

За чем следить и что делать, если что-то пошло не так. Две ситуации, которые похожи, но различаются по сути, техническая пауза платформы и выключение ботов организацией, описаны в отдельных разделах.

Хранение секретов#

У бота два секрета: токен, с которым программа вызывает Bot API, и в режиме webhook секрет webhook, которым SMeet подписывает доставки.

• Храните их в переменных окружения или хранилище секретов. Файл .env должен быть доступен для чтения только пользователю сервиса и никогда не попадать в git.
• Передавайте токен только в заголовке Authorization. Никогда не вставляйте его в URL, лог, чат, скриншот или обращение в поддержку. Примеры пишут в лог идентификаторы событий и чатов и коды ошибок, но не токен, секрет или текст сообщений.
• SMeet показывает каждый секрет один раз и хранит только хэш токена и зашифрованную копию секрета webhook. API не возвращает ни один из них, а токен никогда не передаётся в ваш webhook.
• Смена токена: выпустите новый на защищённом экране «Моих ботов»; старый сразу перестаёт работать, поэтому немедленно впишите новый в программу и перезапустите её.
• Смена секрета webhook: сохраните webhook заново на экране «Подключение»; при каждом включении режима webhook создаётся новый секрет, который показывается один раз. Пока нового секрета нет в программе, доставки с новой подписью не проходят вашу проверку, ваш ответ 401 приостанавливает доставку, и события ждут (Endpoint на паузе). Впишите новый секрет в программу, перезапустите её и нажмите Возобновить доставку; ничего не теряется.
• Если секрет мог утечь, используйте экстренный сброс: новый токен, отобранная аренда long polling и, в режиме webhook, новый секрет webhook за один шаг.

Проверка состояния#

• getMe отвечает, даже когда бот на паузе и во время технической паузы платформы. Вызывайте его при запуске: он подтверждает токен и показывает status (active, paused_by_owner, suspended_by_admin) и delivery_mode.
• getDeliveryInfo служит главным вызовом для мониторинга (Диагностика очереди). Он никогда не возвращает секреты и тоже отвечает во время технической паузы, с "maintenance": true.
• «Мои боты» и карточка бота в BotFather показывают один из четырёх статусов:

«Работает» означает только то, что программа подключена. О правильности её логики статус ничего не говорит, а webhook, который отклоняет события ответами 400, 413 или 422, из-за этого статуса ошибки не получает: следите за списком FAILED и failed_update_count. В режиме webhook SMeet BotFather ещё и пишет вам, когда доставка приостановлена или событие ушло в FAILED (Уведомления владельцу).

Диагностика очереди#

{
  "ok": true,
  "result": {
    "mode": "polling",
    "config_version": "3",
    "pending_update_count": 12,
    "failed_update_count": 1,
    "oldest_pending_date": "2026-09-26T09:58:10Z",
    "confirmed_offset": "1840",
    "lease": {"consumer_id": "poller-host1", "epoch": "7", "expires_at": "2026-09-26T10:01:00Z"},
    "webhook": {"url": "", "state": "none", "pending_update_count": 12, "max_connections": 1},
    "maintenance": false,
    "retention_seconds": 604800
  }
}

Если бот молчит#

1. Запущена ли программа? В её логе должна быть строка Running as @<адрес> и не должно быть ошибок.
2. Работает ли токен? Вызовите getMe с этим токеном. 401 INVALID_TOKEN означает, что токен отозван или скопирован с ошибкой: выпустите новый в «Моих ботах».
3. Работает ли бот? status в getMe: paused_by_owner снимается командой /resume в BotFather; suspended_by_admin означает, что платформа приостановила бота или владелец вышел из организации: обратитесь в поддержку.
4. Тот ли режим? delivery_mode в getMe. Программа long polling при боте в режиме webhook получает 409 DELIVERY_MODE_CONFLICT: переключите бота на long polling или запустите приёмник webhook.
5. Не получает ли события другая копия? lease.consumer_id в getDeliveryInfo. CONSUMER_CONFLICT, который не проходит, означает, что аренду держит вторая копия (Зависшая аренда).
6. Нажал ли человек «Начать»? До нажатия «Начать» и после остановки до бота ничего не доходит. В организации человек должен оставаться её участником.
7. Это платформа или организация? 503 BOTS_MAINTENANCE означает техническую паузу: подождите. 403 SPACE_BOTS_DISABLED означает, что организация выключила ботов.
8. Webhook: state и last_error в getWebhookInfo (Проблемы webhook) и список FAILED. paused означает, что endpoint дал ответ, который можете исправить только вы; исправьте и нажмите Возобновить доставку в «Моих ботах».
9. Не уходят ответы: 403 BOT_STOPPED_OR_BLOCKED (человек остановил бота), 400 INVALID_REQUEST с error.field, 429 RATE_LIMITED. Сохраните request_id неудачного вызова.

Ошибки по HTTP-статусам#

Полный список в таблице кодов ошибок.

Проблемы webhook#

getWebhookInfo показывает состояние вашего endpoint:

next_attempt_date показывает и ожидание после неудачного соединения или ответа 429. last_error.code говорит, что случилось последним:

Могут появиться новые коды; незнакомый код оценивайте по state, который приходит вместе с ним.

Техническая пауза: BOTS_MAINTENANCE#

Операторы SMeet могут приостановить всю платформу ботов, например на время отката выпуска или во время инцидента. Это пауза, а не отзыв разрешения: всё сохраняется.

Во время паузы:

• методы данных Bot API отвечают 503 BOTS_MAINTENANCE с retry_after (30 секунд) и тем же значением в заголовке Retry-After; ожидающие long poll завершаются этой ошибкой;
• getMe, getMyCommands, getDeliveryInfo и getWebhookInfo продолжают отвечать, а getDeliveryInfo показывает "maintenance": true;
• доставка через webhook, которая уже идёт, завершается и засчитывается; новые доставки и проверки файлов не начинаются;
• сообщения людей ботам не отправляются: приложение сообщает, что боты на техническом обслуживании, и оставляет текст в поле ввода;
• очередь, события в FAILED, ключи Idempotency-Key, offset, аренда long polling и разрешения Start сохраняются;
• остановка, блокировка, выход из пространства и удаления по-прежнему действуют и отменяют то, что должны отменять;
• срок хранения продолжает идти: событие, у которого 7 суток закончились во время паузы, истекает.

Что делает программа:

• ждёт retry_after и повторяет тот же запрос с тем же ключом и тем же offset; никогда не сбрасывает сохранённую позицию из-за этой ошибки;
• после паузы getUpdates с теми же consumer_id, epoch и offset продолжает в той же аренде. Если пауза длилась дольше аренды, вызов получает новую, и сохранённый offset всё равно подтверждает события, потому что аренду между тем никто не брал. Ничего не теряется;
• приёмник webhook ничего не делает: доставки возобновятся сами, по порядку.

Клиент примеров делает ровно это: BOTS_MAINTENANCE входит в коды, которые smeet.py повторяет с тем же телом и ключом.

Организация отзывает разрешение#

Владелец или администратор организации может выключить работу ботов (Организации и доступ). Это решение о данных организации, а не техническая пауза, и оно отменяет:

• каждый бот организации получает 403 SPACE_BOTS_DISABLED, а люди видят, что боты в этой организации выключены;
• все недоставленные события этих ботов отменяются, включая события в FAILED; повторить их нельзя, и они не вернутся, когда работу включат снова;
• чаты и разрешения Start сохраняются.

Что делает программа: прекращает вызовы в цикле (примеры завершаются с кодом 2 и сообщением) и обращается к администраторам организации. Когда работу снова включат, запустите программу: она получит только то, что происходит с этого момента, а отменённый диапазон придёт как пропуск с причиной cancelled.

Пауза и приостановка#

Зависшая аренда#

Когда программа long polling падает, её аренда живёт ещё до 60 секунд после последнего ответа сервера этой программе, а оставленный ею long poll считается до конца своего тайм-аута. Перезапущенная программа, которая сохранила epoch, продолжает сразу; потерявшая её получает CONSUMER_CONFLICT, пока аренда не истечёт. getDeliveryInfo показывает держателя в поле lease.

Если вы уверены, что другой копии нет, нажмите Сбросить подключение на экране «Подключение» в «Моих ботах». Старая epoch после этого становится чужой: копия, которая ещё передаёт её, ничего ею не подтвердит, а неподтверждённые ею события придут снова. Следующий вызов получает новую аренду с подтверждённой позиции.

Помощь#

Напишите на support@scrile.com: адрес бота, время, метод и request_id неудачного вызова (он есть в теле каждой ошибки и в заголовке X-Request-Id). Никогда не присылайте токен или секрет webhook.