How to Create a Telegram Bot with a Secure Webhook

Prepare the bot, data boundary, and recovery path

Start with fictional order data and one narrow command. Decide what a Telegram user is allowed to learn before connecting the bot to a real customer or order system.

• A Telegram account and BotFather brief: Choose the bot name, username, `/start` message, supported commands, and one owner who can revoke or rotate access through BotFather. Do not promise commands the first handler does not implement.
• A public HTTPS endpoint: The endpoint must receive raw JSON POST requests, read the secret-token header, return a bounded response quickly, and expose no token in its public path, rendered error, or routine logs.
• A durable update record: Store `update_id`, processing state, attempt count, completion time, and a bounded error code. The sample uses memory only for deterministic tests; production needs a database transaction or equivalent durable claim.
• An authorized order lookup: Define the public identifier, allowed response fields, not-found behavior, rate limit, and whether the chat identity must be linked to a customer. An order number alone may not be adequate authorization for real shipment details.
• A privacy, retention, and contact rule: Publish the policy the bot will actually follow, name who handles deletion requests, decide how long bounded chat and order-link records remain, and keep replies user-initiated unless the person explicitly permits a defined notification. Provide a durable opt-out before enabling proactive sends.

Credentials and access

Telegram Bot API constraints

• Re-checked July 19, 2026 against Telegram Bot API 10.2, current BotFather guidance, the Bots FAQ, and the Bot Platform Developer Terms. Re-check these first-party sources again before registration or publication because setup, limits, and policy terms can change.
• BotFather creates and administers the bot identity. Treat the bot token like a password: keep it server-side, never put it in browser code, a screenshot, a repository, or a logged request URL.
• Telegram supports either `getUpdates` long polling or an outgoing webhook for updates, not both at the same time. The reproduced artifact uses the webhook model.
• A webhook must use HTTPS. Telegram currently documents ports 443, 80, 88, and 8443, retries non-2xx responses for a bounded number of attempts, and retains incoming updates for no longer than 24 hours.
• `secret_token` is 1-256 characters using letters, digits, underscore, or hyphen. Telegram sends it in `X-Telegram-Bot-Api-Secret-Token`; it authenticates the configured webhook but does not replace input validation or access control for your business records.
• Telegram requires an easily accessible privacy policy that describes collected data, purpose, and storage. If Telegram's standard policy does not match the bot, configure a suitable policy through BotFather, delete data on request or when it is no longer needed, and document the retention owner.
• Do not send unsolicited messages, buy or import chat identifiers, or bypass Telegram moderation and rate limits. Keep the default order-status flow user-initiated; any proactive notification needs specific permission, a working opt-out, and suppression of queued sends after revocation.

Official references: Telegram bots and BotFather, Telegram Bot API Update object, Telegram Bot API setWebhook, Telegram Bot API getWebhookInfo, Telegram Bot API sendMessage, Telegram Bot Platform Developer Terms, Telegram Standard Privacy Policy for Bots and Mini Apps

Choose webhook delivery or long polling

Telegram exposes two mutually exclusive update receivers. The right choice depends on where the bot runs and how much operational control you need.

Recommended:Use a webhook for a Playcode-hosted production bot because HTTPS and the handler can run with the app. Use long polling only when you intentionally operate a worker. In either model, persist `update_id` and business writes so a retry cannot duplicate the outcome.

Create a Telegram order-status bot

Create the provider identity, implement and test a secret-validated idempotent webhook, deploy it, register it with Telegram, and operate it safely.

const supplied = headers.get('x-telegram-bot-api-secret-token')
if (!sameSecret(supplied, env.TELEGRAM_WEBHOOK_SECRET)) {
  return Response.json({ ok: false }, { status: 401 })
}

const update = JSON.parse(rawBody)
if (!Number.isSafeInteger(update.update_id) || update.update_id < 0) {
  return Response.json({ ok: false }, { status: 400 })
}

Test security, business input, retries, and the published path

A green local reply test is not enough. Test both the unauthenticated webhook boundary and the provider-controlled delivery path.

Diagnose Telegram bot failures from the boundary inward

Start with provider delivery health, then authentication, update state, business lookup, and outbound delivery. Avoid rotating permissions or secrets without evidence.

Operate the bot as a small production service

Deploy

Deploy the webhook and secrets together, reject unsigned traffic before parsing, and register only the exact HTTPS URL. Treat receiver-mode changes and `drop_pending_updates` as reviewed operations because they can affect queued user actions.

Use a test bot or controlled chat for the first environment smoke. Re-check Telegram's current BotFather, webhook, port, retry, and policy terminology on the day you register or publish.

Monitor

Track request count by status class, secret rejection, invalid payloads, new/completed/duplicate/retryable update counts, handler latency, outbound provider status, queue age, and `getWebhookInfo` pending/error fields.

Track denied or opted-out proactive attempts and Bot API 429 responses as safety signals. Honor `retry_after` rather than bypassing Telegram rate limits, and stop a notification campaign when permission or queue-state checks fail.

Use `update_id` and an internal request ID for correlation. Keep bot tokens, webhook secrets, full chat text, names, order details, consent payloads, and raw provider URLs out of routine logs.

Recover

For an outbound outage, repair the adapter and replay only durable retryable updates. For token exposure, revoke through BotFather, rotate server secrets, re-register, and verify the old token fails.

For a bad release, restore the app to a known point, then reconcile post-checkpoint update and business records separately. Whole-app restore and record-level replay solve different problems.

Protect credentials, chat identity, and business records

The webhook secret authenticates the configured delivery path; it does not authorize a chat to read an order. Apply both boundaries.

• Keep the BotFather token and webhook secret server-side, rotate after exposure, and never render or log a token-bearing Bot API URL.
• Validate the secret header before parsing, bound request size and text length, allow only expected update types, and treat every field as untrusted.
• Authorize order lookup separately from input format. Avoid exposing customer names, addresses, phone numbers, or exact delivery details to a guessed identifier.
• Persist update identity and state durably. Use transactions or an outbox when a process crash between business writes and message delivery could duplicate or lose an effect.
• Keep the bot user-initiated unless a person explicitly permits a defined proactive message. Store the permission version and revocation time, provide an opt-out, and suppress queued sends after revocation. Never purchase or scrape chat IDs.
• Publish an accessible privacy policy, minimize retained chat data, delete it on request or when no longer needed, define deletion ownership, redact logs, rate-limit abusive lookups, and review Telegram policy plus applicable privacy obligations before real customer use.

Telegram bot setup questions