Telegram Bot API via proxy: configurando long polling, webhooks e tratamento do erro 429

Introdução: o que você vai ganhar com este guia

Se você já criou um bot no Telegram pelo menos uma vez, conhece essa situação chata. O bot em si fica pronto numa noite, mas fazer ele rodar de forma estável vira um projeto à parte. As mensagens chegam com atraso, as atualizações se perdem, o servidor de repente recebe um erro 429 e o webhook simplesmente para de ser chamado sem maior explicação. Some a isso um proxy pelo qual todas as requisições precisam passar, e o número de pontos de falha dobra.

Este guia passo a passo resolve exatamente esses problemas. Você vai aprender a trabalhar com a Telegram Bot API através de um servidor proxy de forma que o bot não caia, não perca mensagens e reaja corretamente aos limites. Não vamos falar do protocolo MTProto nem montar um sistema de monitoramento de proxy. Nosso tema é mais específico e mais prático: requisições HTTP para api.telegram.org via proxy, duas formas de receber atualizações e a reação correta aos limites.

O que você vai ter no final

• Um bot funcionando, que envia requisições para a Telegram Bot API através do seu proxy (HTTP ou SOCKS5).
• Long polling configurado, que não quebra por timeout e não duplica mensagens.
• Um webhook com HTTPS e token secreto, recebendo atualizações no seu servidor.
• Um wrapper pronto para as requisições, que espera o tempo necessário no erro 429 e reenvia automaticamente.
• Entendimento de qual modo escolher para o seu projeto: polling ou webhook.

Para quem é este guia

Para profissionais de marketing e afiliados que montam bots para disparos, notificações de leads e estatísticas de campanhas. Para desenvolvedores que precisam de um IP de saída fixo e previsível para requisições de servidor. Para donos de negócio cujos bots atendem clientes e não podem ficar uma hora em silêncio. Se você trabalha com proxies móveis e quer passar o tráfego do bot por eles, chegou ao lugar certo.

O que você precisa saber antes

Explicamos cada passo do zero, mas algumas habilidades básicas vão facilitar bastante a vida. É útil saber abrir um terminal ou prompt de comando, copiar comandos e rodar scripts em Python. Saber o que é uma requisição HTTP e JSON ajuda, mas vamos lembrar tudo em palavras simples. Os tópicos avançados estão numa seção separada, e os iniciantes podem pulá-la sem perder o resultado final.

Quanto tempo vai levar

A preparação e a criação do bot levam cerca de 20 minutos. Configurar o proxy e fazer a primeira requisição bem-sucedida, mais 20 a 30 minutos. O long polling você coloca no ar em meia hora. O webhook exige de 40 a 60 minutos, porque é preciso um certificado HTTPS. O tratamento do erro 429 acrescenta mais uns 20 minutos. No total, de duas a três horas de trabalho tranquilo, com testes em cada etapa.

Preparação inicial: ferramentas e acessos

Antes de escrever a primeira linha de código, vamos reunir tudo o que é necessário. Assim você não vai parar no meio do passo para procurar a senha do proxy ou descobrir como instalar uma biblioteca.

Ferramentas e acessos necessários

1. Conta no Telegram com número vinculado. É com ela que você vai criar o bot pelo bot oficial BotFather.
2. Acesso ao proxy: endereço do servidor, porta, login e senha. No painel da mobileproxy.space esses dados aparecem no cartão do proxy que você comprou. Normalmente há duas portas disponíveis: uma para conexão HTTP e outra para SOCKS5. Anote as duas.
3. Computador ou servidor com Python 3.10 ou mais recente. Para o webhook, você vai precisar de um servidor com IP público e domínio; num computador de casa o webhook não vai funcionar.
4. Utilitário curl. No Windows 10 e 11, no macOS e no Linux ele já vem instalado. Confirme com o comando curl --version.
5. Editor de texto: VS Code, Notepad++ ou qualquer outro onde seja confortável escrever código.

Requisitos de sistema

Para polling quase não há requisitos: qualquer máquina com acesso à internet, inclusive um notebook. O bot consome algumas dezenas de megabytes de memória. Para o webhook é preciso um VPS com configuração mínima: 1 núcleo, 1 GB de memória RAM, Ubuntu 22.04 ou 24.04. É obrigatório ter um domínio apontando para o IP desse servidor e a porta 443 liberada no firewall.

O que instalar

1. Abra o terminal.
2. Verifique o Python com o comando python3 --version. No Windows o comando pode ser python --version.
3. Crie a pasta do projeto: mkdir tgbot-proxy e depois entre nela com cd tgbot-proxy.
4. Crie um ambiente virtual: python3 -m venv venv. Ative-o: no Linux e no macOS source venv/bin/activate, no Windows venv\Scripts\activate.
5. Instale as bibliotecas: pip install requests[socks] flask. O pacote requests cuida das requisições à Telegram Bot API, o complemento socks é necessário para proxies no protocolo SOCKS5, e o Flask recebe o webhook.

Backups e segurança dos dados

Trate o token do bot como se fosse a senha do seu aplicativo de banco. Quem conseguir esse token pode escrever em nome do bot para os seus clientes. Crie um arquivo .env com o token e os dados do proxy e nunca o envie para um repositório público. Se o bot já está em produção e você vai migrá-lo para o proxy, salve a configuração atual, faça uma cópia de segurança do banco de dados, se houver, e anote o resultado do método getWebhookInfo. Assim, o rollback não vai levar mais que dois minutos.

Dica: Crie um bot de teste separado para os experimentos. Faça todos os passos deste guia primeiro nele, e migre para o bot de produção apenas a configuração já validada. Assim você não corre o risco de atrapalhar o atendimento aos clientes reais.

Conceitos básicos: como funciona a Telegram Bot API

Vamos entender os termos-chave em palavras simples. Sem eles, os próximos passos vão parecer mágica; com eles, tudo fica lógico e previsível.

Telegram Bot API

É uma interface HTTP comum. Seu código envia uma requisição para um endereço no formato https://api.telegram.org/bot<TOKEN>/<método>, e o servidor do Telegram responde com um objeto JSON. Por exemplo, o método getMe retorna informações do bot, e o sendMessage envia um texto para o chat. Não é preciso biblioteca especial: curl ou requests já bastam. É justamente por isso que a Telegram Bot API é tão fácil de passar por um proxy: é o mesmo tráfego de qualquer site via HTTPS.

Atualizações (updates)

Cada evento para o bot, seja mensagem, clique em botão ou entrada em grupo, chega como um objeto update com um número único, o update_id. Os números crescem em ordem. A missão do seu código é receber esses objetos e processá-los. Existem exatamente duas formas de fazer isso, e elas são mutuamente exclusivas.

Long polling (polling longo)

Seu bot pergunta ao Telegram: tem novidade para mim? Ele faz isso pelo método getUpdates. A palavra "long" significa que o servidor não responde imediatamente com uma lista vazia, mas mantém a conexão aberta até o timeout informado, geralmente de 30 a 60 segundos, e responde na hora assim que surge um evento. Isso economiza requisições e dá reação quase instantânea. O polling não exige endereço público, funciona atrás de roteador e através de qualquer proxy. É ideal para começar e para bots com pouca carga.

Webhook

A abordagem inversa. Você informa ao Telegram o endereço do seu servidor pelo método setWebhook, e o Telegram passa a enviar cada atualização como requisição POST para esse endereço. Você não precisa consultar nada. Os requisitos: domínio público, certificado HTTPS e uma das portas 443, 80, 88 ou 8443. O webhook escala melhor e não gasta recursos esperando.

Importante entender: o proxy afeta apenas as requisições de saída do seu bot para o Telegram. As requisições recebidas pelo webhook chegam direto ao seu servidor e o proxy não entra nessa cadeia. Então, na prática, a expressão "webhook via proxy" significa: o bot responde e chama os métodos da API pelo proxy, mas recebe as atualizações no seu endereço público.

Erro 429 Too Many Requests

O Telegram limita a frequência de requisições. Referências para 2026: no máximo uma mensagem por segundo num chat, no máximo 20 mensagens por minuto num grupo e cerca de 30 mensagens por segundo somadas em todo o bot. Ao ultrapassar esses limites, o servidor devolve o status HTTP 429 e, no corpo da resposta, o campo parameters.retry_after com a quantidade de segundos de espera. Ignorar isso não é opção: tentativas repetidas sem pausa aumentam o tempo de bloqueio.

Por que usar proxy para um bot, afinal

Os motivos são bem práticos. Primeiro, um IP de saída fixo e previsível: é útil quando há muitos servidores, mas você precisa de um endereço externo único. Segundo, separação de tráfego por projeto: cada cliente ou campanha com o seu canal. Terceiro, políticas corporativas, quando todas as conexões externas precisam passar por um gateway. Aqui os proxies móveis se destacam pela estabilidade e pela possibilidade de trocar o IP por agendamento ou por link.

Passo 1: Criando o bot e obtendo o token

Objetivo da etapa: obter o token de acesso à Telegram Bot API e confirmar que o bot existe.

1. Abra o Telegram no celular ou no computador.
2. Na barra de busca, digite BotFather. Escolha o bot com o selo azul de verificação; os falsos não têm esse selo.
3. Clique em Start ou envie o comando /start. Você verá a lista de comandos disponíveis.
4. Envie o comando /newbot.
5. O BotFather vai pedir o nome do bot. Digite o nome exibido, por exemplo Bot Teste Proxy. Pode conter espaços e acentos.
6. Depois ele pede o username. Ele precisa ser único, em letras latinas, e terminar com bot, por exemplo proxy_test_2026_bot. Se o nome já estiver em uso, o BotFather avisa; invente outro.
7. Na resposta vem uma mensagem de parabéns e uma linha no formato 123456789:AAExampleTokenLettersAndDigits. Esse é o token. Copie-o inteiro, incluindo os dígitos antes dos dois-pontos.
8. Crie na pasta do projeto o arquivo .env e coloque nele a linha BOT_TOKEN=seu_token.

Atenção: Nunca publique o token em chats, capturas de tela ou repositórios abertos. Se o token vazar, envie imediatamente o comando /revoke ao BotFather, escolha o bot e obtenha um novo token. O antigo deixa de funcionar na hora.

Primeira requisição sem proxy

Antes de complicar o esquema, vamos verificar se o token funciona com uma requisição simples a partir da sua máquina. Rode no terminal, substituindo pelo seu token:

curl https://api.telegram.org/bot123456789:AAExampleToken/getMe

Resposta esperada: um JSON começando com {"ok":true,"result":{"id":123456789,"is_bot":true,.... Dentro dele você vai ver o username do bot que acabou de criar.

Verificação: A resposta contém "ok":true e o username correto. Se, em vez disso, vier "error_code":401, o token foi copiado com erro; confira se algum caractere das pontas não ficou de fora.

Possíveis problemas

• Username em uso. Acrescente números ou uma sigla do projeto, só preserve o final bot.
• BotFather não responde. Confirme que abriu o bot com o selo de verificação, e não um homônimo.
• Erro 404 Not Found. Faltou a palavra bot antes do token no endereço. O formato é rigorosamente /bot<TOKEN>/método.

Passo 2: Conectando o proxy e testando o acesso à API

Objetivo da etapa: fazer as requisições à Telegram Bot API passarem pelo seu proxy e confirmar isso na prática, não só na teoria.

Entendendo o formato do endereço do proxy

O proxy é descrito numa única linha: protocolo://login:senha@host:porta. Pegue os dados no painel. Suponhamos que você recebeu o host proxy-host, a porta HTTP 8080, a porta SOCKS5 1080, login user e senha pass. As linhas ficariam assim:

• Proxy HTTP: http://user:pass@proxy-host:8080
• Proxy SOCKS5: socks5h://user:pass@proxy-host:1080

Repare na letra h em socks5h. Ela significa que o nome de domínio api.telegram.org será resolvido do lado do proxy, e não na sua máquina. Essa é a opção correta para proxies móveis: as consultas DNS e o tráfego seguem pelo mesmo caminho. Sem a letra h, se houver problema com o DNS local, as requisições vão falhar mesmo com o proxy em pleno funcionamento.

Se a senha tiver caracteres como @, : ou /, eles precisam ser codificados: @ vira %40, os dois-pontos viram %3A e a barra vira %2F. Caso contrário, a linha será interpretada errado.

Teste com curl

1. Primeiro, descubra qual IP os serviços externos enxergam através do seu proxy. Rode: curl -x http://user:pass@proxy-host:8080 https://api.ipify.org. Ele vai retornar um endereço IP. Ele precisa ser diferente do seu endereço de casa ou do servidor.
2. Agora a mesma requisição para a Telegram Bot API: curl -x http://user:pass@proxy-host:8080 https://api.telegram.org/bot123456789:AAExampleToken/getMe.
3. Para SOCKS5, troque o parâmetro: curl -x socks5h://user:pass@proxy-host:1080 https://api.telegram.org/bot123456789:AAExampleToken/getMe.
4. Meça o tempo de resposta: acrescente ao final do comando -w " tempo: %{time_total}". Um valor até 1-2 segundos para proxy móvel é normal.

Verificação: As duas requisições retornaram "ok":true, e o IP da primeira é diferente do seu. Isso significa que a rota pelo proxy funciona e a Telegram Bot API responde por ela.

Configurando o proxy no Python

Crie o arquivo config.py com o conteúdo abaixo, substituindo os valores pelos seus:

import os
TOKEN = os.getenv('BOT_TOKEN', '123456789:AAExampleTokenReplaceMe')
PROXY = os.getenv('BOT_PROXY', 'http://user:pass@proxy-host:8080')
PROXIES = {'http': PROXY, 'https': PROXY}
BASE = f'https://api.telegram.org/bot{TOKEN}'

A chave https no dicionário é obrigatória, porque a Telegram Bot API só funciona por HTTPS. Um erro comum de iniciante é informar apenas http e não entender por que o tráfego está indo direto.

Agora o script de teste check.py:

import requests
from config import PROXIES, BASE
ip = requests.get('https://api.ipify.org', proxies=PROXIES, timeout=15).text
print('IP de saída:', ip)
me = requests.get(f'{BASE}/getMe', proxies=PROXIES, timeout=15).json()
print('Bot:', me['result']['username'])

Rode: python check.py. Na tela vão aparecer o IP do proxy e o username do bot.

Dica: Se você não quiser mexer no código da biblioteca que já usa, defina a variável de ambiente HTTPS_PROXY=http://user:pass@proxy-host:8080. A biblioteca requests e a maioria dos clientes HTTP a capturam automaticamente. É uma forma prática de migrar um bot já existente para o proxy sem alterações no código.

Configuração nos frameworks mais usados

• aiogram 3.x: crie a sessão AiohttpSession(proxy='http://user:pass@proxy-host:8080') e passe-a na criação do objeto Bot(token=TOKEN, session=session). Para SOCKS5, será necessário o pacote aiohttp-socks.
• python-telegram-bot 21.x: use HTTPXRequest(proxy='http://user:pass@proxy-host:8080') e passe-o em ApplicationBuilder().token(TOKEN).request(request).
• Node.js: os pacotes https-proxy-agent ou socks-proxy-agent criam um agente que é passado nas opções do cliente HTTP ou no construtor da biblioteca de bot.

Possíveis problemas

• 407 Proxy Authentication Required. Login ou senha incorretos, ou caracteres especiais não codificados. Confira os dados no painel.
• Connection refused. Porta incorreta ou portas HTTP e SOCKS5 trocadas. Tente a outra porta.
• A requisição vai direto. A chave https não está no dicionário, ou a variável de ambiente foi definida em outra janela do terminal.
• Erro de SSL. Não desligue a verificação do certificado. Atualize o pacote certifi com pip install -U certifi e confira o relógio do sistema.

Passo 3: Colocando o long polling no ar via proxy

Objetivo da etapa: ter um bot funcionando, que através do proxy busca atualizações pelo método getUpdates e responde às mensagens, sem perder nem duplicar nada.

Como montar o ciclo de polling corretamente

A lógica é simples, mas os detalhes importam. Você chama getUpdates com o parâmetro offset igual ao último update_id processado mais um. Assim o Telegram entende que as atualizações anteriores foram recebidas e as apaga do lado dele. Se esquecer o offset, a mesma mensagem volta de novo e de novo, e o bot começa a responder várias vezes.

O parâmetro timeout define quantos segundos o servidor mantém a conexão aguardando eventos. Aí começa a particularidade do proxy. Todo proxy tem o seu próprio timeout de conexão ociosa, e nos proxies móveis ele costuma ficar entre 60 e 120 segundos. Se o timeout do polling for maior, o proxy corta a conexão antes de o Telegram responder, e você recebe erro em vez de atualizações. Um valor seguro é timeout=50 com o timeout do cliente HTTP em 60 segundos. O timeout do cliente deve ser sempre maior que o do polling, senão o cliente cai primeiro.

Escrevendo o bot

1. Crie o arquivo polling.py.
2. Copie o código abaixo.
3. Rode com python polling.py.
4. Envie qualquer mensagem ao bot no Telegram.

import time, requests
from config import PROXIES, BASE
offset = 0
print('Polling iniciado via proxy')
while True:
try:
r = requests.get(f'{BASE}/getUpdates', params={'offset': offset, 'timeout': 50}, proxies=PROXIES, timeout=60)
data = r.json()
except requests.RequestException as e:
print('Erro de rede:', e)
time.sleep(3)
continue
if not data.get('ok'):
print('Erro da API:', data)
time.sleep(3)
continue
for upd in data['result']:
offset = upd['update_id'] + 1
msg = upd.get('message')
if msg and 'text' in msg:
requests.post(f'{BASE}/sendMessage', json={'chat_id': msg['chat']['id'], 'text': 'Recebido: ' + msg['text']}, proxies=PROXIES, timeout=15)

Vamos entender o que acontece aqui. O laço externo nunca termina sozinho. O bloco try captura erros de rede: quebra do proxy, timeout, troca de IP. Em caso de erro, o script espera três segundos e tenta de novo, em vez de cair. A checagem data.get('ok') captura erros de nível da API. O laço interno processa cada atualização e avança o offset na hora.

Verificação: Apareceu no console a linha de início, e depois que você mandou a mensagem o bot respondeu "Recebido: seu texto". Envie três mensagens seguidas: o bot deve responder exatamente uma vez a cada uma. Pare o script com Ctrl+C, mande uma mensagem e rode de novo: o bot vai responder à mensagem perdida, porque o Telegram guarda atualizações não processadas por até 24 horas.

Particularidades dos proxies móveis no polling

Os proxies móveis conseguem mudar o endereço IP: por agendamento ou por um link especial no painel. No momento da troca de IP, a conexão de polling aberta é interrompida. Isso não é erro do seu código, é comportamento normal da rede. Nosso laço já está pronto para isso: ele captura a exceção, espera e continua do mesmo offset. Nenhuma atualização se perde.

Ainda assim, uma rotação frequente gera ruído extra nos logs e microatrasos. Recomendação: para bot em polling, configure no painel um intervalo de rotação de 10 minutos ou mais, ou desligue a troca automática e mude o IP pelo link apenas quando for realmente necessário. Um bot não é um scraper; ele não precisa de um endereço novo a cada minuto.

Dica: Registre no log a hora e o update_id de cada atualização. Quando, uma semana depois, alguém disser que o bot não respondeu, em um minuto você vai descobrir se a mensagem chegou ao seu código ou se o problema foi na rede.

Possíveis problemas

• Erro 409 Conflict. O mais comum. O bot tem um webhook configurado, e polling e webhook não podem funcionar ao mesmo tempo. Rode curl -x seu_proxy https://api.telegram.org/botTOKEN/deleteWebhook e reinicie o script. A segunda causa: há duas cópias do script rodando; encerre a que sobra.
• O bot responde duas vezes a cada mensagem. O offset não avança ou há duas cópias do bot rodando.
• Read timed out constante. O timeout do polling é maior que o do proxy. Reduza o timeout para 30-40 segundos.
• Atraso de 5 a 10 segundos na resposta. Verifique o tempo de resposta do proxy com curl. Se o próprio canal é lento, troque o ponto de saída ou o plano.

Passo 4: Configurando o webhook com HTTPS e token secreto

Objetivo da etapa: o Telegram envia as atualizações direto para o seu servidor, e o bot responde pelo proxy. Esta etapa exige um VPS com domínio; então, se por enquanto você só tem polling e ele atende bem, pode ir para o passo 5 e voltar aqui depois.

Preparando o servidor e o domínio

1. Contrate um VPS com Ubuntu. Anote o IP público dele.
2. No painel do seu domínio, crie um registro A, por exemplo bot.example.com, apontando para o IP do servidor. Aguarde a propagação do DNS, normalmente de 5 a 30 minutos. Confirme com nslookup bot.example.com.
3. Conecte-se ao servidor por SSH e atualize os pacotes: sudo apt update.
4. Instale o nginx e o certbot: sudo apt install nginx certbot python3-certbot-nginx.
5. Libere as portas 80 e 443: sudo ufw allow 80, sudo ufw allow 443.
6. Obtenha um certificado gratuito: sudo certbot --nginx -d bot.example.com. Siga as instruções, informe o e-mail e aceite os termos. Em um minuto o certificado será emitido.

O Telegram só aceita webhooks por HTTPS com certificado válido de uma autoridade confiável. O certificado do certbot atende a esse requisito. Um certificado autoassinado também é possível, mas aí a parte pública dele precisaria ser enviada no parâmetro certificate do setWebhook, e isso dá mais trabalho. Para iniciantes, o certbot é mais simples.

Configurando o nginx como ponto de entrada

O nginx vai receber as requisições HTTPS do Telegram e repassá-las para a sua aplicação Flask, que escuta na porta local 8080. Abra o arquivo de configuração do site criado pelo certbot com sudo nano /etc/nginx/sites-available/default e adicione dentro do bloco server com a porta 443 um location assim:

location /tg/webhook {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_read_timeout 30s;
}

Salve o arquivo, confira a sintaxe com sudo nginx -t e recarregue com sudo systemctl reload nginx.

Dica: Deixe o caminho do webhook nada óbvio, por exemplo /tg/webhook/k8s7d2f. Isso não substitui o token secreto, mas é uma camada extra: scanners aleatórios não vão achar o seu ponto de entrada.

Escrevendo o handler do webhook

Crie no servidor o arquivo webhook.py. Ele recebe o POST do Telegram, valida o cabeçalho secreto e responde ao usuário através do proxy. A função call vamos escrever no próximo passo; por enquanto, use requests.post comum com proxies.

import requests
from flask import Flask, request, abort
from config import PROXIES, BASE
app = Flask(__name__)
SECRET = 'MySecret123'
@app.post('/tg/webhook')
def webhook():
if request.headers.get('X-Telegram-Bot-Api-Secret-Token') != SECRET:
abort(403)
update = request.get_json(silent=True) or {}
msg = update.get('message')
if msg and 'text' in msg:
requests.post(f'{BASE}/sendMessage', json={'chat_id': msg['chat']['id'], 'text': 'Recebido via webhook'}, proxies=PROXIES, timeout=15)
return 'ok', 200
if __name__ == '__main__':
app.run(host='127.0.0.1', port=8080)

O ponto central é o cabeçalho X-Telegram-Bot-Api-Secret-Token. O Telegram o adiciona a cada requisição quando você informa o secret_token na configuração do webhook. Qualquer requisição sem o valor correto é rejeitada com código 403. Assim, ninguém de fora consegue injetar mensagens falsas no bot.

Inicie a aplicação: python webhook.py. Para produção, mais tarde, transforme em serviço systemd, mas para testar o disparo direto já basta.

Registrando o webhook através do proxy

A própria chamada setWebhook também passa pelo proxy, pois é uma requisição de saída para a Telegram Bot API. Rode em qualquer máquina com acesso ao proxy:

curl -x http://user:pass@proxy-host:8080 -F "url=https://bot.example.com/tg/webhook" -F "secret_token=MySecret123" -F "max_connections=40" -F "drop_pending_updates=true" https://api.telegram.org/bot123456789:AAExampleToken/setWebhook

Vamos entender os parâmetros. url: o endereço do seu handler. secret_token: uma string de 1 a 256 caracteres com letras latinas, números, hífen e underscore; ela precisa ser igual ao SECRET no código. max_connections: quantas requisições simultâneas o Telegram pode abrir para você, de 1 a 100, com padrão 40. drop_pending_updates: descarta as atualizações acumuladas, para o bot não despejar uma avalanche de respostas antigas no momento da troca.

Resposta esperada: {"ok":true,"result":true,"description":"Webhook was set"}.

Diagnóstico com o getWebhookInfo

É a principal ferramenta de depuração de webhooks. Execute:

curl -x http://user:pass@proxy-host:8080 https://api.telegram.org/bot123456789:AAExampleToken/getWebhookInfo

Olhe os campos da resposta: url precisa bater com o seu, pending_update_count mostra a fila de atualizações não processadas, e last_error_date e last_error_message aparecem se o Telegram não conseguiu entregar uma atualização. O campo de erro vazio após enviar uma mensagem de teste significa sucesso total.

Verificação: Mande uma mensagem ao bot. Ele respondeu "Recebido via webhook". No getWebhookInfo não há last_error_message, e o pending_update_count está zerado. Nos logs do Flask aparece a linha com POST /tg/webhook e código 200.

Atenção: O handler do webhook precisa responder rápido, em poucos segundos. Se o seu código demora, por exemplo com uma consulta pesada ao banco ou a um serviço externo via proxy lento, o Telegram considera a entrega falha e repete. Jogue o trabalho pesado numa tarefa em segundo plano e devolva 200 imediatamente ao webhook.

Possíveis problemas

• last_error_message: SSL error. Certificado inválido, vencido ou emitido para outro domínio. Verifique com sudo certbot certificates.
• Connection timed out. Porta 443 fechada no firewall ou na hospedagem. Confira sudo ufw status e as configurações no painel do VPS.
• Wrong response from the webhook: 403. O token secreto no código e no setWebhook não coincidem. Confira o uso de maiúsculas e minúsculas.
• Wrong response from the webhook: 502. O Flask não está rodando ou escuta em outra porta. Confira com ss -tlnp | grep 8080.
• Bad webhook: port not allowed. Use apenas 443, 80, 88 ou 8443.

Passo 5: Tratando o erro 429 e deixando as requisições resistentes

Objetivo da etapa: escrever uma função única para todas as chamadas à Telegram Bot API, que aguenta a pausa no 429, repete a requisição em caso de falhas de rede e do proxy, e nunca derruba o bot.

Por que o 429 não pode ser ignorado

Quando você dispara uma mensagem para mil usuários, o limite de 30 mensagens por segundo é atingido na hora. O Telegram responde 429 e informa o retry_after. Se você continuar martelando o servidor, as mensagens não vão sair, e o tempo de espera nas próximas respostas só vai aumentar. Trabalhando com proxy há um detalhe: os limites do Telegram estão ligados ao bot, não ao IP. Trocar o IP pela rotação não ajuda a contornar a limitação e não deve ser usada para isso. O único caminho correto é respeitar o retry_after e controlar a velocidade de envio.

Escrevendo o wrapper universal

Adicione ao arquivo config.py, ou a um arquivo separado api.py, a seguinte função:

import time, requests
from config import PROXIES, BASE
def call(method, payload, retries=6):
for attempt in range(retries):
try:
r = requests.post(f'{BASE}/{method}', json=payload, proxies=PROXIES, timeout=15)
except requests.RequestException as e:
print('Rede ou proxy:', e)
time.sleep(min(2 ** attempt, 30))
continue
if r.status_code == 429:
wait = r.json().get('parameters', {}).get('retry_after', 1)
print('429 Too Many Requests, aguardando', wait, 'seg')
time.sleep(wait + 0.5)
continue
if 500 <= r.status_code < 600:
print('Erro do servidor do Telegram', r.status_code)
time.sleep(min(2 ** attempt, 30))
continue
data = r.json()
if not data.get('ok'):
print('Erro da API:', data.get('description'))
return data
raise RuntimeError('Telegram Bot API: tentativas esgotadas para ' + method)

O que essa função faz. Em erro de rede, espera exponencialmente: 1, 2, 4, 8 segundos, mas nunca mais que 30. Assim o bot sobrevive à troca de IP do proxy ou a uma breve falha de canal. No 429, lê o retry_after, acrescenta meio segundo de folga e repete. Em erros 5xx do lado do Telegram, também repete com pausa. Em erros 400 ou 403, por exemplo quando o usuário bloqueou o bot, repetir é inútil, então a função devolve a resposta como está, e você decide o que fazer.

Limitando a velocidade desde o começo

Melhor nem chegar ao 429. Para disparos em massa, acrescente uma pausa entre as mensagens. O mais simples: time.sleep(0.05) após cada envio, o que dá 20 mensagens por segundo, abaixo do limite geral. Para um único chat, mantenha a pausa de pelo menos um segundo. Para grupos, não mais de 20 mensagens por minuto.

def broadcast(chat_ids, text):
sent, failed = 0, 0
for cid in chat_ids:
res = call('sendMessage', {'chat_id': cid, 'text': text})
if res.get('ok'):
sent += 1
else:
failed += 1
time.sleep(0.05)
print('Enviadas:', sent, 'Erros:', failed)

Dica: Guarde as respostas com erro 403 Forbidden: bot was blocked by the user. Remova esses usuários da base de disparo. Isso reduz a carga e protege de limites desnecessários, pois as requisições que falham também contam.

Testando o tratamento do 429

1. Crie um grupo de teste e adicione o bot lá.
2. Rode um laço de 40 chamadas call('sendMessage', {...}) para esse chat, sem pausas.
3. Observe no console: depois de alguns envios rápidos, vai surgir a linha sobre o 429 e o tempo de espera.
4. Confirme que, depois da pausa, o envio continuou e as 40 mensagens chegaram.

Verificação: Todas as mensagens entregues, o bot não caiu com exceção e no log aparecem as pausas do retry_after. Substitua o requests.post em polling.py e webhook.py pela função call, para que todo o trabalho com a Telegram Bot API passe por um único canal protegido.

Possíveis problemas

• retry_after gigante, centenas de segundos. Você ignorou o limite por muito tempo. Pare todo o envio, aguarde o tempo indicado e reduza o ritmo.
• 429 já nas primeiras mensagens. Outro processo está usando o mesmo token. Verifique se não há uma versão antiga do bot rodando.
• Resposta não JSON no 429. Alguns proxies devolvem a própria página HTML de erro. Envolva o r.json() num try e, em caso de falha, espere 5 segundos fixos.

Passo 6: Configurações avançadas para projetos com carga

Objetivo da etapa: preparar o bot para crescer: vários bots por vários proxies, fila de envio, servidor local da Bot API e rotação bem planejada. Os iniciantes podem pular esta seção e voltar quando os usuários passarem de mil.

Vários bots por proxies diferentes

Profissionais de marketing costumam operar uma dezena de bots para projetos diferentes num único servidor. A arquitetura correta: cada bot com seu próprio dicionário proxies e sua própria sessão requests.Session(). A sessão reaproveita conexões TCP, o que reduz a carga no proxy e acelera as requisições de 2 a 3 vezes. Guarde a configuração como uma lista: token, endereço do proxy, modo de recebimento de atualizações. Um processo por bot é mais fácil de depurar do que um processo para todos.

Fila de envio em vez de chamadas diretas

Para disparos a partir de 10 mil usuários, chamadas diretas no código principal deixam de funcionar. Monte uma fila: Redis ou, no mínimo, uma tabela no banco com os campos chat_id, text, status, attempts. Um worker separado pega as tarefas e chama a função call com controle de velocidade. No 429, o worker dorme, em vez de bloquear o recebimento dos webhooks. Assim o bot continua respondendo a comandos do usuário enquanto o disparo roda em segundo plano. Em 2026, a Telegram Bot API permite que bots pagos, via o parâmetro allow_paid_broadcast, elevem o limite a 1000 mensagens por segundo, mas isso consome Stars; então, para a maioria dos projetos, a fila com 20-25 mensagens por segundo segue sendo a melhor opção.

Servidor local da Bot API

O Telegram publica o código-fonte do servidor da Bot API, que você pode rodar na sua máquina. Seu código então se comunica com localhost, não com api.telegram.org, e o servidor local conversa com o Telegram. Vantagens: upload de arquivos de até 2 GB em vez de 50 MB, webhooks em qualquer porta e sem HTTPS dentro da sua rede, além da remoção de alguns limites. Desvantagem: o proxy precisa ser configurado no próprio servidor local, e não no código do bot. É uma opção para equipes com competências de DevOps; para começar, é exagero.

Rotação de IP e webhooks

Com webhooks, a rotação de IP no proxy quase não se nota: cada chamada sendMessage é curta, e a quebra de conexão na hora da troca afeta no máximo uma requisição, que o wrapper call vai repetir. Por isso, com webhooks é aceitável rotacionar com mais frequência do que no polling. Ainda assim, não faz sentido trocar com frequência: a Telegram Bot API não limita requisições por IP, e os limites estão no token. Configure a rotação pensando na sua infraestrutura, e não em função da API.

Monitoramento de saúde sem sistema à parte

O mínimo que vale a pena montar desde o início: a cada minuto, chame getWebhookInfo e escreva no log o pending_update_count e o last_error_message. Se a fila crescer em três medições seguidas, seu handler não está dando conta. Para polling, registre a hora do último getUpdates bem-sucedido: se passou mais de dois minutos, a conexão travou, reinicie o processo. Isso já basta para saber dos problemas antes dos clientes.

Dica: Registre não só os erros, mas também o tempo de cada requisição à Telegram Bot API pelo proxy. Um crescimento lento do tempo médio de resposta de 0,3 para 2 segundos avisa sobre a degradação do canal dias antes de o bot começar a perder mensagens.

Verificação do resultado: checklist da solução pronta

Passe pela lista. Cada item precisa estar marcado; só assim o bot está pronto para trabalhar com usuários reais.

Checklist

• O comando curl com o parâmetro -x via proxy retorna "ok":true no método getMe.
• O script check.py mostra o IP do proxy, e não o seu próprio.
• O polling responde a cada mensagem uma única vez, sem duplicatas.
• Depois de parar e reiniciar o polling, as mensagens perdidas são processadas.
• Ao forçar a troca de IP no proxy, o polling se recupera sozinho em 3-5 segundos.
• Webhook: o getWebhookInfo mostra a sua url, pending_update_count zerado e last_error_message vazio.
• Uma requisição ao webhook sem o cabeçalho secreto recebe 403.
• O envio rápido de 40 mensagens para um chat passa sem queda, e no log aparecem as pausas do retry_after.
• O token e os dados do proxy estão no .env, e não no código.

Como testar de ponta a ponta

1. Inicie o bot no modo escolhido.
2. Envie de três contas diferentes duas mensagens cada uma.
3. Confirme as seis respostas, uma para cada mensagem.
4. Clique no painel do proxy o link de troca de IP e envie mais uma mensagem na hora.
5. O bot precisa responder em até 10 segundos.
6. Rode o teste de 429 do passo 5.
7. Confira os logs: nenhuma exceção não tratada nem stack trace.

Indicadores de sucesso

Tempo de resposta do bot a uma mensagem de até 2 segundos. Proporção de requisições malsucedidas à Telegram Bot API após todas as repetições abaixo de 0,1%. Nenhuma duplicata em 24 horas de operação. O pending_update_count no getWebhookInfo não passa de dez nos horários de pico. Se os números batem, parabéns: você montou um esquema confiável que vai durar muitos meses.

Erros comuns e como resolver

Erro 409 Conflict no getUpdates

Causa: o bot tem um webhook configurado, ou há duas instâncias de polling rodando. Solução: chamar deleteWebhook pelo proxy e garantir que só há um processo rodando. Verifique com o comando ps aux | grep polling.

O bot responde duas vezes a cada mensagem

Causa: o offset não aumenta, ou há duas cópias do bot rodando em servidores diferentes com o mesmo token. Solução: confira a linha offset = update_id + 1 e encerre as cópias extras. Para webhook, garanta que o nginx não duplica as requisições para dois backends.

Erro 407 Proxy Authentication Required

Causa: credenciais do proxy incorretas ou caracteres especiais não codificados na senha. Solução: confira login e senha no painel, codifique @, : e / na senha e tente autenticação por IP, se ela estiver disponível no seu plano.

Read timed out a cada 50-60 segundos

Causa: o timeout do polling é maior ou igual ao timeout de ociosidade do proxy. Solução: reduza o timeout no getUpdates para 30-40 segundos e mantenha o timeout do cliente 10 segundos acima.

Webhook configurado, mas as atualizações não chegam

Causa: porta fechada, certificado inválido ou handler que não responde 200. Solução: olhe o last_error_message no getWebhookInfo; ele dá o diagnóstico exato. Confira com curl -I https://bot.example.com/tg/webhook a partir de outro computador.

Wrong response from the webhook: 403 Forbidden

Causa: o token secreto no código é diferente do informado no setWebhook. Solução: reinstale o webhook com o mesmo valor do código. Lembre-se de que o setWebhook com novos parâmetros substitui completamente os anteriores.

429 constantes com carga pequena

Causa: o bot envia para um mesmo chat com frequência maior que uma vez por segundo, por exemplo várias mensagens seguidas em resposta a um único comando. Solução: junte as respostas numa única mensagem, use editMessageText em vez de novas mensagens para acompanhar progresso e adicione pausa entre envios para o mesmo chat_id.

O tráfego vai direto, sem passar pelo proxy

Causa: falta a chave https no dicionário proxies, a variável de ambiente não está visível ao processo ou o framework não captou a configuração. Solução: verifique o IP de saída com uma requisição a api.ipify.org dentro do mesmo código com que você envia as mensagens. Não confie em suposições, verifique na prática.

SSL: CERTIFICATE_VERIFY_FAILED nas requisições via proxy

Causa: conjunto de certificados raiz desatualizado ou hora do sistema errada. Solução: atualize o certifi e sincronize a hora. Nunca desligue a verificação de certificado com o parâmetro verify=False: isso abre a possibilidade de troca de tráfego com o token.

FAQ: perguntas frequentes sobre a configuração

O que usar para começar: polling ou webhook?

Polling. Ele funciona de qualquer lugar, não exige domínio nem certificado, e migrar para webhook depois leva uma hora. Webhook faz sentido quando o bot atende milhares de usuários ou roda num servidor que já tem HTTPS.

Posso usar o mesmo proxy para vários bots?

Sim. Os limites da Telegram Bot API estão ligados ao token do bot, não ao IP. Dez bots por um só proxy não atrapalham uns aos outros do ponto de vista da API. A única limitação é a banda do próprio proxy, que para bots de texto sobra com folga.

É obrigatório passar tanto o webhook quanto as respostas pelo proxy?

As requisições recebidas pelo webhook chegam direto ao seu servidor; por definição, não há como passá-las pelo proxy. Pelo proxy só passam as chamadas de saída: sendMessage, setWebhook, getFile e os demais métodos. Esse é o esquema normal e o único possível.

Como saber se as requisições estão de fato passando pelo proxy?

Dentro do mesmo código, faça uma requisição para https://api.ipify.org com as mesmas configurações de proxies e compare com o seu IP real. Como reforço, veja as estatísticas de tráfego no painel do proxy: o contador deve subir enquanto o bot trabalha.

O que fazer quando o IP do proxy muda com o bot rodando?

Nada, se você usou o código deste guia. O polling captura a quebra de conexão e continua do offset salvo. A função call repete a requisição que falhou. A única recomendação é não configurar rotação mais frequente que a cada poucos minutos no modo polling.

SOCKS5 ou proxy HTTP para a Telegram Bot API?

Para o bot, a diferença é quase nenhuma; os dois funcionam. O proxy HTTP é mais simples de configurar e é suportado por todos os clientes sem pacotes extras. O SOCKS5 é mais conveniente quando você quer garantir a resolução de DNS do lado do proxy com o esquema socks5h. Escolha o que você já usa em outros projetos.

Quantas mensagens dá para enviar sem tomar 429?

Fique dentro das referências: até 1 mensagem por segundo num chat privado, até 20 por minuto num grupo, até 25-30 por segundo no total. Para disparos em massa, planeje 20 mensagens por segundo e trate sempre o retry_after, porque os limites podem cair temporariamente quando o Telegram está sob carga alta.

Como migrar com segurança um bot que já está rodando para o proxy?

Primeiro teste o proxy com curl no getMe. Depois adicione a variável HTTPS_PROXY ou configure proxies no código, rode o bot com um token de teste. Só após os testes darem certo troque para o token de produção. Mantenha a configuração antiga à mão para fazer rollback.

Como reverter o webhook e voltar ao polling?

Uma chamada deleteWebhook pelo proxy. Se quiser preservar as atualizações acumuladas para o polling, não informe drop_pending_updates. Depois disso, inicie polling.py e o bot vai pegar a fila.

Dá para configurar vários URLs de webhook para um mesmo bot?

Não, cada bot tem exatamente um webhook. Se precisar distribuir a carga, coloque na frente do único URL um balanceador nginx, que repassa as requisições para várias instâncias da aplicação. Para o Telegram, isso continua sendo um único ponto de entrada.

Conclusão

Vamos resumir o trabalho feito. Você criou o bot e obteve o token, aprendeu a testar o proxy com curl e Python, confirmou que o tráfego para a Telegram Bot API segue pelo caminho certo. Montou um ciclo de long polling resistente, que sobrevive à troca de IP e não duplica mensagens. Configurou o webhook com certificado HTTPS de verdade e o protegeu com um token secreto. E o mais valioso: escreveu uma função que respeita o retry_after no 429, repete requisições em falhas de rede e transforma um canal instável num canal confiável.

O que fazer agora. Transforme o bot num serviço systemd, para que ele suba depois de uma reinicialização do servidor. Mova os tokens e endereços de proxy para variáveis de ambiente na máquina de produção. Adicione um log simples com o tempo das respostas e revise-o uma vez por semana. Se os usuários aumentarem muito, parta para a fila de envio da seção avançada.

Para onde evoluir. Estude os métodos da Telegram Bot API para botões inline, pagamentos e mini apps; eles abrem cenários totalmente novos para marketing e vendas. Aprenda frameworks assíncronos como aiogram ou python-telegram-bot, que assumem a rotina do polling e das repetições, e você já entende o que acontece por baixo do capô deles. E o principal: não tenha medo de experimentar num bot de teste. Cada erro 429 ou 409 que você mesmo encontra e corrige deixa você mais forte do que qualquer template pronto. Você vai conseguir.

Sobre o autor

Roman Melnikov

Technical Writer and System Administrator

Experiência profissional: Technical writer and DevOps engineer with 9 years of experience. Created over 50 detailed guides on system configuration and administration. His instructions helped thousands of professionals successfully solve technical tasks. Popular author on Habr and YouTube.

Formação: Bauman Moscow State Technical University. Information Systems and Technologies

Especialização:

Technical Documentation DevOps System Administration Linux Docker and Kubernetes CI/CD Infrastructure Automation Cloud Technologies System Monitoring Bash and Python Scripting