Skip to main content

Bot launch checklist: security, retries, logs, and functional checks

Verify bot token and Webhook security, retry handling, logging, and smoke tests for delivery, callbacks, and blocked private chats.

In this guide, DocOnly and L0–L3 describe testing precautions and operation risks, not whether an API method is supported. Check official support status separately; verify targets and recovery steps before changing messages, chats, or delivery settings.

Tick every box before go-live. Review token handling, event delivery and retries, and safeguards for high-risk methods.

Overview

A pre-launch checklist grouped by concern. Pair it with the smoke test at the end.

Token security

  • Token only in secret management / environment variables, never in the repo.

  • Separate tokens for production and test bots.

  • CI/CD injects secrets; nothing printed to build logs.

  • A documented token-leak rotation SOP exists.

Webhook security

  • HTTPS public URL.

  • secret_token set and the X-MpChat-Bot-Api-Secret-Token header validated.

  • The webhook endpoint does not expose admin interfaces.

  • Verify in a test environment before running setWebhook on production.

Rate limits and retries

  • Client-side throttle at or below 30 req/s per token.

  • Back off on 429. For 500 or a timeout, confirm the operation can be retried safely before sending it again. Treat 400/401/403 as errors to resolve before retrying. For 409, check whether Webhook is enabled.

  • Bound concurrency for batch operations.

Log redaction

  • No token, full initData, or sensitive user fields in logs.

  • Error reporting has redaction rules.

  • Access logs do not store the full webhook URL with its secret.

High-risk APIs (DocOnly, require approval + rollback)

  • logOut, leaveChat, deleteMessage(s), banChatMember, setWebhook, deleteWebhook.

  • Deployment pipelines contain no automatic calls to these.

  • The runbook records the approver and rollback steps.

Smoke test

  1. getMe — token valid.

  2. getWebhookInfo — URL correct.

  3. Simulate a user message — webhook receives the update.

  4. sendMessage — reply succeeds.

  5. (If applicable) initData verification passes.

  6. With the test bot, simulate a failed Webhook delivery and confirm the same update_id arrives again. Verify a single business action is recorded.

  7. If the bot uses callback buttons, verify that the first answer succeeds and a duplicate answer returns HTTP 400.

  8. In a test private chat, block the bot and verify that send, forward, and copy each return HTTP 403. Unblock the bot and verify a new send succeeds.

What does a retry or an empty queue mean?

  • Webhook retries keep the original update_id. After validating the request, persist the update with a unique key scoped to the bot and update_id before returning HTTP 2xx (for example, 200 or 204). Make business actions idempotent as well, so processing a job again cannot duplicate a reply or a state change.

  • Ordinary updates can be delivered for up to 24 hours. Callback updates have up to 150 seconds for delivery, with a separate 300-second window for answerCallbackQuery.

  • pending_update_count=0 means no updates are currently pending. Check getWebhookInfo for recent delivery errors and compare with your own receipt and processing logs to confirm what reached your service.

Related

Related Articles
Did this answer your question?