Most Telegram bot tutorials end at "it works for one bot". Our platform runs a few hundred merchant bots (shops, paid channels, AI assistants) from one Node.js cluster, and almost every hard bug we hit only appeared at that scale. Here are the lessons, in the order they hurt.
1. One process cannot own every bot: shard by bot
A single Node process runs out of event-loop headroom long before it runs out of memory. We run one primary process plus a pool of worker processes, and each bot belongs to exactly one worker. The reverse proxy routes every webhook request to the worker that owns that bot (a stable hash of the bot id), so a bot's updates are always handled in one place, in order, with its in-memory state.
The rule that keeps this sane: anything that must happen once (schedulers, reminders, cleanup jobs) runs only on the primary, and every worker checks "do I own this bot?" before acting.
2. Start bots slowly, or Telegram will rate-limit all of them
On boot, the naive code calls getMe and setWebhook for every bot at once. With hundreds of bots that is a burst of thousands of requests, and Telegram answers with 429 Too Many Requests and a retry_after that can lock bots out for minutes. Every restart degraded every bot.
Fixes that worked:
- Cache
getMeresults in the database and only refresh them in the background. - Check
getWebhookInfofirst and callsetWebhookonly when the URL or settings are actually wrong. - Spread the remaining calls over time with a small queue, and honour
retry_afterwhen it is short. Give up and retry later when it is long.
3. Answer the webhook fast and do the work after
Telegram waits for your HTTP response. If your handler awaits a database call, an AI model or a file upload before answering, slow requests pile up and Telegram starts retrying, so you get the same update twice.
Reply 200 as soon as the update is validated and queued, then process it. The exception is payments: save a pre_checkout_query or a successful payment durably before you answer, because that is the one place where losing an update costs real money.
4. Deduplicate updates by update_id
Retries, restarts and proxy hiccups all produce duplicates. Keep the last few thousand update_ids per bot (an LRU in memory is enough for most of them) and drop repeats before any handler runs. For anything that moves money, add a second, durable "processed" table keyed by the callback or payment id, so a duplicate can never pay out twice even across a restart.
5. Use secret_token on every webhook
setWebhook accepts a secret_token, and Telegram sends it back in the X-Telegram-Bot-Api-Secret-Token header on every request. Check it, and reject requests without it. Also keep the bot token out of the webhook URL: URLs end up in proxy access logs, monitoring tools and error reports. Use an opaque id in the path instead.
6. Be careful what shutdown does
A classic trap is a "clean" shutdown handler that deletes each bot's webhook on SIGTERM. It looks tidy, but a routine restart then unregisters every bot the process owned. Shutdown handlers should stop taking new work and flush queues. They should not change anything on Telegram's side.
Related: wrap startup code so that one bad module cannot crash the process on load. With a cluster, a crash on load is a silent total outage, because every worker dies the same way.
7. Rate-limit per user and per bot
One user tapping a button 50 times a second, or one bot being flooded, should not slow every other bot down. A sliding window per (bot, user) and per bot, checked before any handler, keeps the noise out. Escalate repeat offenders to temporary bans rather than answering every request.
8. Your bot library will silently drop new update types
Telegram keeps adding update types. In November 2026 Bot API 10.4 added widget_query for interactive widget cards. Older libraries only dispatch the types they know, so new ones vanish without an error. If you rely on a library, check how it handles unknown updates, and handle new types yourself before the library's dispatcher. (I wrote up the widget case here: Telegram widgets: interactive cards inside chat messages.)
Also remember allowed_updates: if you ever set an explicit list, new types are not delivered until you add them.
The short version
- Shard bots across workers, one owner per bot.
- Run schedulers on one process only.
- Start slowly and cache
getMe. - Answer fast, but save payments first.
- Dedupe by
update_id, and durably for money. - Use
secret_tokenand keep tokens out of URLs. - Make shutdown boring.
- Rate-limit per user and per bot.
- Watch for new update types.
These lessons come from building TeleCrow, a no-code platform for Telegram shop bots, paid-channel bots and AI assistants. If you run many bots yourself, I hope this saves you a few late nights.
Disclosure: I work on TeleCrow.
Top comments (1)
On #1, routing a bot to one worker doesn't by itself keep its updates in order. setWebhook has
max_connections, default 40, so Telegram can have several requests for the same bot open at once, and once handlers await a DB call they finish in whatever order. Two quick messages from one user in an FSM-style flow ("send your address", then "send your phone") can get processed swapped. What I'd do is a small promise chain per chat_id inside the owning worker, so one chat runs serially and different chats stay parallel. Settingmax_connections: 1also works but caps throughput for the busy bots.On #3, if the queue behind the early 200 is in memory, a crash or deploy between the 200 and the handler loses the update for good, since Telegram won't send it again after a 200. Fine for "hi" messages, worth a durable queue for anything like orders or subscriptions, same as you do for payments.
(I use AI tools to help me write and check code.)