Skip to content
Guide

Telegram bots: webhook vs polling in production

By Fayez AlshamiPublished: Updated: 4 min read
TL;DR

Use long polling while you build on a laptop; switch to an HTTPS webhook with a secret header check when the shop bot lives on a VPS. Telegram delivery and wallet confirmation are different problems - you still match transaction ID and amount through your gateway, with no memo field on the transfer.

When I first shipped a Telegram shop bot, I left it on long polling because that is what the quick start uses. It worked on my laptop. On a VPS I had two processes polling the same token after a sloppy restart, and updates arrived twice or not at all. The payment logic was fine. The delivery method was not.

Polling and webhook are two ways Telegram gives your bot the next chat update. They are not two ways to confirm a Syriatel Cash transfer. Confirmation is still a lookup of the transaction ID and a comparison with the order amount, and those transfers have no memo field. The bot walkthrough is in How to build a Telegram bot that accepts Syriatel Cash. Store-owner questions around that flow are in Syriatel Cash payment bots: common questions.

What I use where

I use long polling while I am writing the conversation: no public HTTPS, no DNS, one process on my machine calling getUpdates. I also leave a tiny internal bot on polling if it runs as a single supervised process.

In production, for a shop that takes orders or payments, I switch to a webhook. Telegram then posts each update to a URL I control, on a server I already keep online, behind TLS. A practical path for putting a Node.js process behind Nginx is in نشر مشروع Node.js على VPS. The same idea applies if the bot is Python: one process, HTTPS in front, token only in the environment.

You cannot usefully run both at once on the same bot token. Setting a webhook tells Telegram to stop serving getUpdates. If a leftover poller is still running, you will chase empty responses and wonder why the shop is silent.

A minimal webhook in production

Telegram requires HTTPS for the webhook URL. I terminate TLS at Nginx and let the bot listen on localhost. I also set a secret token and check the X-Telegram-Bot-Api-Secret-Token header so a stranger cannot post fake updates to the path.

```javascript import express from "express";

const app = express(); app.use(express.json());

const SECRET = process.env.TELEGRAM_WEBHOOK_SECRET;

app.post("/telegram/webhook", (req, res) => { if (req.get("x-telegram-bot-api-secret-token") !== SECRET) { return res.status(401).end(); } res.status(200).end(); handleUpdate(req.body).catch((err) => console.error(err)); });

app.listen(3000, "127.0.0.1");

async function handleUpdate(update) { const message = update.message; if (!message?.text) return; // Create the order or read a pasted transaction ID here. } ```

Reply 200 as soon as you have accepted the JSON, then do the work. If you wait on a payment lookup before responding, Telegram may retry the same update and your handler must tolerate a second delivery. That is the same discipline I use for payment provider callbacks in Reliable payment webhooks: acknowledge quickly, apply the event once.

Register the URL once after deploy, with the secret, and do not leave a poller running:

``bash curl -sS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \ -d "url=https://example.com/telegram/webhook" \ -d "secret_token=${TELEGRAM_WEBHOOK_SECRET}" ``

Replace the host with yours. Keep the bot token out of git and out of the Nginx access log. If you need to go back to polling in an emergency, call deleteWebhook first, then start a single getUpdates process.

Mistakes that show up after go-live

Two app instances both expose the webhook, or one still polls. Telegram delivers each update once to the URL. Your own fleet can process it twice if you do not lock on update_id. Store processed update IDs for a few days, the same way you store a payment event ID.

A webhook on a laptop path or an HTTP URL. Telegram will reject it. Use a real certificate and a hostname that stays pointed at the VPS.

Treating the Telegram webhook as proof of payment. An update that says the customer pasted an ID only means the chat received text. You still ask the hosted gateway to look up that ID and compare the amount. I run that gateway for Syriatel Cash ($2 per number per month) and Sham Cash ($5 per account per month). Setup is same day, and you do not receive source code. The sender number comes back with every transfer and I save it, but I do not match on it.

Dropping handleUpdate errors on the floor with no retry for side effects, such as an admin notification. The chat update can be marked done while the merchant never hears about a paid order. Queue that message separately and do not roll the order status back because Telegram was briefly unreachable.

Frequently asked questions

Is polling unsafe in production?

It can work for a single supervised process. The failure I see is a second copy after a deploy, or a host that sleeps and lets the getUpdates offset drift. For a payment bot I still prefer a webhook on a server that is already meant to stay up.

Do I need a webhook from Telegram and from the payment gateway?

They do different jobs. Telegram tells you the customer typed something. The payment webhook tells you a transfer was seen even if the customer never came back to the chat. Many shops start with a pasted transaction ID and add the payment webhook later.

What if my VPS has no HTTPS yet?

Stay on polling until TLS is in place, or put a reverse proxy with a certificate in front. Do not point setWebhook at a plain HTTP URL and hope.

Guides & comparisons

Need this built or connected for your business?

See services