Bot do Telegram não responde: webhook, polling e erros comuns

Quando um bot do Telegram fica mudo, nenhuma tela vermelha diz o porquê. O Telegram entrega updates por HTTP, então o silêncio pode vir de três lugares: o token, o seu processo ou o caminho entre o Telegram e o processo (polling ou webhook). Se você perguntar à própria API, descobre qual é em dois minutos.

A ordem que mais economiza tempo é esta: validar o token, ver como os updates chegam e só então olhar as causas específicas. Para a base de como o bot recebe updates, veja como hospedar um bot do Telegram 24/7.

Como descobrir onde está o problema?#

Defina o token numa variável de ambiente (nunca cole em chat ou repositório) e rode este script. Ele usa só a biblioteca padrão do Python:

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"))

Leia o resultado assim:

• getMe dá erro 401 Unauthorized: o token está errado ou foi revogado. Nada mais importa até corrigir isso.
• getWebhookInfo com url preenchida: o bot está em modo webhook. Veja pending_update_count (updates esperando entrega), last_error_date e last_error_message (o último erro ao entregar).
• url vazia: o bot deveria estar em polling. Se não responde, o problema é o processo ou um conflito de instâncias.

Se getMe funciona e o processo está rodando, mas nada chega, siga para as seções abaixo. O log do processo quase sempre completa o quadro.

O problema está no token ou no processo?#

São as duas causas mais simples de conferir, então vale descartá-las primeiro.

O token está certo?#

Um 401 vem de token errado, copiado com espaço sobrando ou revogado. A revogação acontece quando você gera um novo token no @BotFather (o anterior deixa de valer) ou quando revoga um token que vazou. Confira se a variável de ambiente no servidor tem o valor atual, sem aspas nem quebra de linha. Para o conceito, leia o que são variáveis de ambiente.

O processo está rodando?#

Parece óbvio, mas é uma das causas mais comuns: o bot rodava no seu computador e o computador dormiu, reiniciou ou perdeu a conexão. Em servidor, o processo pode ter caído por erro não tratado ou falta de memória. Procure no log a última exceção antes do silêncio e confira se há reinício automático. O artigo sobre monitorar o uptime de um bot mostra como receber o aviso antes que os usuários percebam.

Se o bot ficou fora do ar, os updates não se perdem na hora: o Telegram guarda os pendentes até o bot buscá-los, por no máximo 24 horas.

Por que aparece "Conflict: terminated by other getUpdates request"?#

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

Só uma conexão de getUpdates pode existir por bot. Se duas instâncias fazem polling com o mesmo token, uma derruba a outra, e o comportamento fica intermitente: ora responde, ora não. As origens mais comuns:

• o bot ainda rodando no seu PC, esquecido num terminal;
• um deploy novo que subiu antes de o antigo parar;
• dois containers ou réplicas do mesmo serviço.

A correção é deixar uma única instância por token. Se você quer separar desenvolvimento de produção, crie dois bots no @BotFather, cada um com seu token.

Webhook e polling estão brigando?#

Um bot usa um método de cada vez. Enquanto há webhook configurado, o getUpdates não recebe nada. O caso clássico: você testou um webhook, depois fez o deploy do código em polling e o bot ficou calado. O getWebhookInfo mostra a url ainda registrada. Remova-a:

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

O contrário também vale: depois de um setWebhook, o polling para de funcionar. Para descartar a fila acumulada ao trocar de método, passe drop_pending_updates ao deleteWebhook ou ao setWebhook.

Por que o webhook não entrega updates?#

Quando last_error_message aparece no getWebhookInfo, o Telegram tentou entregar e falhou. Verifique, nesta ordem:

1. HTTPS válido. Não existe webhook em HTTP puro, e o Telegram exige TLS 1.2 ou superior. Certificado expirado, domínio diferente do certificado ou cadeia sem o certificado intermediário causam erro de SSL. Veja também erros de certificado SSL.
2. Porta permitida. Só 443, 80, 88 e 8443.
3. Alcançável de fora. O servidor precisa estar acessível pelo endereço público. Um firewall bloqueando a porta, ou o processo escutando só em 127.0.0.1, impede a entrega. O Telegram envia de faixas de IPv4 (149.154.160.0/20 e 91.108.4.0/22); IPv6 não é suportado em webhooks.
4. Segredo conferindo. Se você definiu secret_token (1 a 256 caracteres), o Telegram o envia no cabeçalho X-Telegram-Bot-Api-Secret-Token. Se o seu código rejeita a requisição porque o cabeçalho não confere, o bot parece mudo.
5. Resposta rápida. Responda com 200 logo e processe o trabalho pesado em segundo plano. Um handler que trava ou lança erro deixa o Telegram sem resposta.

Depois de corrigir, chame getWebhookInfo de novo: pending_update_count deve cair e last_error_message deve parar de mudar.

O bot funciona no privado mas não em grupos?#

É o privacy mode, ligado por padrão. Nele, o bot em grupo recebe só comandos endereçados a ele (como /ajuda@meu_bot) e respostas às suas mensagens. Mensagens comuns do grupo não chegam. Há duas saídas: desligar o modo com /setprivacy no @BotFather (depois remova o bot do grupo e adicione de novo para a mudança valer) ou promover o bot a administrador do grupo.

O bot para de responder só sob carga?#

Pode ser limite de envio. A FAQ do Telegram orienta não passar de cerca de uma mensagem por segundo no mesmo chat, e bots não conseguem enviar mais de 20 mensagens por minuto num grupo. Em disparos em massa, o limite é de cerca de 30 mensagens por segundo, a menos que o bot ative as transmissões pagas do Telegram. Acima disso, a API responde 429 e as mensagens do bot falham. Use uma fila que espace os envios e trate o erro 429 em vez de repetir o envio em laço.

Como evitar que aconteça de novo?#

• Uma instância por token e variáveis de ambiente no servidor, não no código.
• Logs acessíveis e um alerta externo de disponibilidade.
• Reinício automático do processo.
• Um comando /ping no bot e, em webhook, um olhar periódico no last_error_message.

Como fazer isso na Square Cloud#

Várias causas desta lista (processo parado, variável de ambiente errada, log que ninguém lê) dependem de onde o bot roda. A Square Cloud é hospedagem self-service: você faz o deploy do bot, define a memória e controla tudo pelo painel. Ela suporta python-telegram-bot, aiogram, Telethon, Telegraf e grammY, com long polling sem configuração ou um subdomínio HTTPS para webhooks.

Os containers ficam sempre ligados, sem modo de suspensão, e o reinício automático (ligado por padrão no deploy pelo painel) traz o bot de volta quando o processo encerra com erro. As variáveis de ambiente (como BOT_TOKEN) são definidas por aplicação e valem no próximo restart. Os logs em tempo real mostram o Conflict ou o erro que derrubou o processo.

Todos os planos são pagos e cobrados em reais. O Hobby custa R$ 12,49 por mês, com 1 GB de RAM compartilhado entre suas aplicações, e o mínimo para uma aplicação de fundo como um bot é 256 MB. Os detalhes estão na página de hospedagem de bot do Telegram.