Telegram bot not responding: webhook and polling pitfalls

When a Telegram bot goes quiet, nothing tells you why. Telegram delivers updates over HTTP, so the silence can come from three places: the token, your process, or the path between Telegram and your process (polling or a webhook). If you ask the API itself, you can find out which in two minutes.

The order that saves the most time is this: validate the token, check how updates arrive, then look at specific causes. For the basics of how a bot receives updates, see how to host a Telegram bot 24/7.

How do I find where the problem is?#

Put the token in an environment variable (never paste it in a chat or a repository) and run this script. It uses only the Python standard library:

import json
import os
import urllib.request

TOKEN = os.environ["BOT_TOKEN"]


def call(method: str) -> dict:
    url = f"https://api.telegram.org/bot{TOKEN}/{method}"
    with urllib.request.urlopen(url, timeout=10) as r:
        return json.load(r)


print("getMe:", call("getMe"))
print("getWebhookInfo:", call("getWebhookInfo"))

Read the output like this:

• getMe fails with 401 Unauthorized: the token is wrong or revoked. Nothing else matters until this is fixed.
• getWebhookInfo shows a url: the bot is in webhook mode. Check pending_update_count (updates waiting for delivery), last_error_date and last_error_message (the most recent delivery error).
• Empty url: the bot should be polling. If it does not answer, the problem is the process or an instance conflict.

If getMe works and the process is running but nothing arrives, move on to the sections below. The process log almost always completes the picture.

Is it the token or the process?#

These are the two simplest causes to check, so rule them out first.

Is the token correct?#

A 401 comes from a wrong token, one copied with a stray space, or a revoked one. Revocation happens when you generate a new token in @BotFather (the previous one stops working) or revoke a leaked one. Check that the environment variable on the server holds the current value, without quotes or a trailing newline. For the concept, read what are environment variables.

Is the process running?#

It sounds obvious, but it is one of the most common causes: the bot ran on your computer, and the computer slept, rebooted or lost its connection. On a server, the process may have crashed from an unhandled error or run out of memory. Look in the log for the last exception before the silence and check for automatic restarts. The article on monitoring bot uptime shows how to get alerted before your users notice.

If the bot was down, updates are not lost right away: Telegram keeps pending ones until the bot fetches them, for up to 24 hours.

Why do I see "Conflict: terminated by other getUpdates request"?#

telegram.error.Conflict: Conflict: terminated by other getUpdates request;
make sure that only one bot instance is running

Only one getUpdates connection can exist per bot. If two instances poll with the same token, one kicks the other out, and the behavior becomes intermittent: sometimes it answers, sometimes not. The usual sources:

• the bot still running on your PC, forgotten in a terminal;
• a new deploy that came up before the old one stopped;
• two containers or replicas of the same service.

The fix is a single instance per token. To separate development from production, create two bots in @BotFather, each with its own token.

Are the webhook and polling fighting?#

A bot uses one method at a time. While a webhook is set, getUpdates receives nothing. The classic case: you tested a webhook, then deployed polling code and the bot stayed silent. getWebhookInfo still shows the registered url. Remove it:

curl "https://api.telegram.org/bot${BOT_TOKEN}/deleteWebhook"

The reverse also holds: after a setWebhook call, polling stops working. To discard the accumulated queue when switching, pass drop_pending_updates to deleteWebhook or setWebhook.

Why is the webhook not delivering updates?#

When last_error_message appears in getWebhookInfo, Telegram tried to deliver and failed. Check, in this order:

1. Valid HTTPS. Plain HTTP webhooks do not exist, and Telegram requires TLS 1.2 or higher. An expired certificate, a domain that does not match the certificate, or a chain missing the intermediate certificate causes SSL errors. See also SSL certificate errors.
2. Allowed port. Only 443, 80, 88 and 8443.
3. Reachable from outside. The server must be reachable at the public address. A firewall blocking the port, or a process listening only on 127.0.0.1, stops delivery. Telegram sends from IPv4 ranges (149.154.160.0/20 and 91.108.4.0/22); IPv6 is not supported for webhooks.
4. Matching secret. If you set a secret_token (1 to 256 characters), Telegram sends it in the X-Telegram-Bot-Api-Secret-Token header. If your code rejects requests because that header does not match, the bot looks dead.
5. Fast response. Return 200 quickly and do heavy work in the background. A handler that hangs or throws leaves Telegram without an answer.

After fixing it, call getWebhookInfo again: pending_update_count should drop and last_error_message should stop updating.

Does it work in private chat but not in groups?#

That is privacy mode, on by default. With it, a bot in a group only receives commands addressed to it (like /help@my_bot) and replies to its messages. Ordinary group messages do not arrive. There are two ways out: turn it off with /setprivacy in @BotFather (then remove the bot from the group and add it again so the change applies) or make the bot a group admin.

Does it stop responding only under load?#

It may be a sending limit. Telegram's FAQ advises staying around one message per second in the same chat, and bots cannot send more than 20 messages per minute in a group. For mass broadcasts, the limit is about 30 messages per second unless the bot enables Telegram's paid broadcasts. Beyond that, the API returns 429 and the bot's messages fail. Add a queue that spaces out sends, and handle the 429 instead of retrying in a tight loop.

How do I keep it from happening again?#

• One instance per token, and configuration in server environment variables, not in code.
• Accessible logs and an external uptime alert.
• Automatic process restart.
• A /ping command in the bot and, in webhook mode, a periodic look at last_error_message.

How to do this on Square Cloud#

Several causes on this list (a stopped process, a wrong environment variable, a log nobody reads) depend on where the bot runs. Square Cloud is self-service hosting: you deploy the bot, set its memory and control everything from the dashboard. It supports python-telegram-bot, aiogram, Telethon, Telegraf and grammY, with long polling that needs no setup, or an HTTPS subdomain for webhooks.

Containers stay on, with no sleep mode, and automatic restart (on by default for dashboard deploys) brings the bot back when the process exits with an error. Environment variables (such as BOT_TOKEN) are set per application and apply on the next restart. Real-time logs show the Conflict or the error that took the process down.

All plans are paid and billed in reais. Hobby costs R$12.49 per month, with 1 GB of RAM shared across your applications, and the minimum for a background application such as a bot is 256 MB. The details are on the Telegram bot hosting page.