TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram

Webhook vs Long Polling for Telegram Bots

· 4 min read · 18+ readers

Webhook vs Long Polling for Telegram Bots: TSocial guide cover card

A Telegram bot icon bot must receive updates from Telegram. There are two supported ways: your program asks for them (long polling with getUpdates) or Telegram pushes them to your server (a code icon webhook set with setWebhook). Both deliver the same update objects. This guide helps you pick one and switch safely.

How long polling works

Your program calls getUpdates with a timeout, for example 30 seconds. Telegram holds the request open until an update arrives or the timeout ends. You process the updates, then call again with offset set to the highest update_id plus one. That confirms the earlier updates so they are not sent again.

const r = await api("getUpdates", { offset, timeout: 30, allowed_updates: ["message", "callback_query"] });

Strengths:

  • Works anywhere with outbound internet access, including your laptop.
  • No public address, certificate or domain needed.
  • Easy to debug.

Weaknesses:

  • Needs a process that stays running.
  • You must manage reconnects and offsets.
  • Only one consumer may poll a bot at a time. A second one causes 409 Conflict.

How a webhook works

You tell Telegram a public HTTPS address with setWebhook. For every update Telegram sends an HTTP POST with the update as JSON. Your server replies with a 2xx status quickly. If it does not, Telegram retries for a while.

curl "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  -d url="https://bot.example.com/telegram" \
  -d secret_token="a-long-random-string"

Strengths:

  • No constant polling. It suits serverless platforms that run only when a request arrives.
  • Updates arrive as they happen.
  • Easy to scale behind a load balancer.

Weaknesses:

  • Needs a public HTTPS endpoint with a valid certificate.
  • You must return fast, so slow work needs a queue.
  • You must verify requests really come from Telegram. See secret token setup.
  • Harder to run on a laptop, though tunnels exist for testing.

Rules to remember

  • Webhook and getUpdates are mutually exclusive. While a webhook is set, getUpdates fails. Use deleteWebhook before polling again.
  • Webhooks allow only certain ports. The documentation lists 443, 80, 88 and 8443.
  • HTTPS is required. A self-signed certificate is possible if you upload the public key, but a normal certificate from a public authority is simpler.
  • getWebhookInfo shows the current URL, pending update count and the last error. Use it first when something fails.
  • drop_pending_updates on setWebhook or deleteWebhook discards the backlog.

Which should you choose

SituationSuggestion
Learning, prototypesLong polling
Bot on a small server that stays upEither; webhook is cleaner
Serverless (functions)Webhook
Several instances for loadWebhook
No public domainLong polling
Strict firewalls blocking inbound trafficLong polling

Migrating safely

From polling to webhook:

  1. Deploy your HTTPS endpoint and test it with a manual POST.
  2. Stop the polling process.
  3. Call setWebhook with your URL and secret token.
  4. Call getWebhookInfo and check there is no error.
  5. Send the bot a message and watch your logs.

From webhook to polling: call deleteWebhook, then start polling.

Handling duplicates

Telegram can retry an update if your server did not answer in time, so make handlers idempotent. Store the last handled update_id and skip repeats, or design operations so that doing them twice is harmless. This matters most for payments and for anything that send icon (paper plane) sends messages.

Performance tips

  • Acknowledge first, work later. Return 200 immediately and process in the background.
  • Set allowed_updates to what you need, to reduce traffic.
  • Use max_connections on webhooks to limit parallel deliveries if your server is small.

Quick checklist

  • Decide polling for development and webhook for production.
  • Never run both for one token.
  • Use allowed_updates to receive only what you handle.
  • Reply fast on a webhook and queue slow work.
  • Make handlers safety icon safe to run twice.
  • Check getWebhookInfo after every change.
  • Keep only one polling instance.
  • Document how to switch back.

A note on ordering

Telegram delivers updates in order for a bot, but parallel webhook workers can process them out of order. If order matters, such as for steps in a conversation, store state in a database and check it, or serialise work per chat. Do not rely on the order in which your workers finish.

Frequently asked questions

Can I run both polling and a webhook?

No. Choose one at a time per bot token.

Does a webhook cost more?

Not by itself. Hosting differs. Serverless webhooks can be very cheap for small bots.

Why do I get 409 Conflict?

Two processes are polling, or a webhook is set while you call getUpdates. See common errors.

Can I test a webhook locally?

Yes, with a tunnelling tool that gives you a public HTTPS URL. Remove the webhook when finished.

Related guides

More in Build on Telegram

All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial

Webhook vs Long Polling for Telegram Bots | TSocial