Telegram Bots: Webhooks vs Long Polling

sync Asking, or being called

Asking means your program opens a connection to Telegram and waits, holding it open until something arrives or a timeout passes, then asks again immediately. It needs nothing of you except the ability to make an outbound connection, which is why it works on a laptop, behind a corporate firewall, and on a home network with no fixed address.

Being called means you register a public address and Telegram sends each update to it as it happens. It needs a reachable server with a valid certificate, and in exchange nothing of yours has to be running in a loop.

Note what is not the difference, despite being the headline everywhere. The delay in the asking model is the gap between one request finishing and the next starting, which is milliseconds, not the timeout you configured. For a bot that answers people, both modes feel instant, and choosing on latency grounds is choosing on the least significant axis.

account_tree What each mode actually asks of you

Read the last column first. That is where the choice is usually made in practice, once something has gone wrong.

You cannot run both at once, and switching between them is a configuration change rather than a rewrite — provided you did not build the rest of the bot around one of them. Keeping the handling logic independent of how updates arrived is the small discipline that makes the switch a five-minute job later.

The sensible default is to start by asking. It removes an entire category of setup from the period when you are still deciding what the bot does, and it runs identically on your own machine and on a server. Move to being called when a continuously running process is genuinely inconvenient, or when you need more than one worker.

bolt The rule that causes most webhook bugs

Answer immediately; do the work afterwards.

An endpoint that performs a slow operation before replying — a database write, a call to another service, generating something — will eventually take too long. The delivery is treated as failed and retried. Your slow operation then runs again, possibly several times, for the same event. This is the origin of the duplicate replies, double charges and repeated posts that characterise a certain kind of bot.

The fix is structural rather than a matter of being faster. Accept the update, acknowledge it, put it on a queue, and let something else do the work. And make the handling safe to run twice, because retries are normal and a system that only behaves correctly when each event arrives exactly once is a system waiting for a bad afternoon.

The same discipline pays off in the asking model for a different reason: a handler that blocks holds up everything behind it, so one slow operation stalls the bot for every user at once.

history_toggle_off What happens while your bot is off

This is the fact worth carrying away even if you never write a line of code, because it shapes what you can promise.

Updates are held for a limited period and then discarded. A bot that was stopped for an afternoon receives what accumulated when it comes back; a bot that was stopped for a week does not receive the week. Nobody is notified, and the messages people sent are simply never processed.

Two consequences. For anything transactional — an order, a payment, a request for access — the queue of pending updates is not a reliable store, and a system that depends on eventually receiving everything needs a way to reconcile from its own records. And when you take a bot down deliberately, say so in the bot itself beforehand, because the alternative is people writing into a void and concluding they were ignored.

A smaller related control: you can limit which kinds of update you receive at all. A bot that only answers commands does not need to be sent every edited message in every group it is in, and narrowing this reduces both the traffic and the chance of reacting to something you never intended to handle.

shield A public endpoint receives whatever anybody sends

The moment you register an address, it is on the public internet and will be probed. Two defences, in order of importance.

Use the shared secret. Telegram can include a value of your choosing with every delivery, which your endpoint checks before doing anything. Requests without it are rejected without being parsed. This is cheap, it is built for exactly this, and it is skipped surprisingly often.

Do not trust the contents regardless. A correct secret proves the request came from Telegram; it does not make the data inside it trustworthy, because the data inside it is whatever a stranger typed into your bot. Everything in an update is user input: names, message text, file names, the contents of a button. Treat it the way you would treat a form submission from the open web, which is to say not at all.

And the credential rule from Step 086 applies with particular force here: the address itself is not a secret, but the token is, and a token in a deployment script, a container image or a log line is a token that has left the building.

touch_app Try it now — five minutes

Four steps. The second one produces the most instructive failure in this step.

1. Run a bot in asking mode on your own machine No address, no certificate, no hosting. Fifteen lines and it answers you.
2. Start a second copy of it Watch the two of them take alternate messages, and notice that nothing anywhere says this is what is happening. Now you will recognise it in production.
3. Stop the bot, send it three messages, start it again The three arrive. That tells you the holding behaviour exists; the section above tells you not to rely on it.
4. Write down where your token is stored If the answer involves a file you edit, fix that before anything else in this step matters.

speed The scaling question, answered honestly

Most bots never need to think about throughput, and the ones that do hit a different wall from the one they expected.

The constraint is almost never receiving. Both modes deliver updates faster than a typical bot needs. What limits a busy bot is sending: Telegram paces how quickly a bot may send messages, particularly into a single chat, and any design that broadcasts to a long list of people runs into that rather than into anything about webhooks. A bot messaging thousands of users is a queue with a rate limit, and building it as a loop that sends as fast as it can is the reason it fails.

The second constraint is your own slow work. If each update triggers a call to something external, your capacity is that external thing's capacity, and no delivery mode changes it. This is the case for the queue in the section above: it converts a spike in arrivals into a longer queue rather than into failures.

Which leaves the honest summary. Choose asking for simplicity, choose being called when you need several workers or dislike an idle process, and put your engineering effort into the queue, the retries and the rate limiting — because that is where the problems will actually be.

help Common questions at this stage