Configuração de webhook de bot do Telegram: guia completo para desenvolvedores

A configuração de webhook de bot do Telegram conecta seu servidor ao fluxo de atualizações do Telegram para que as mensagens cheguem em tempo real, em vez de em um loop de polling. Se você está construindo um bot personalizado com a Bot API, webhooks são o caminho de produção padrão: o Telegram POSTa cada atualização para seu endpoint HTTPS, e seu código responde.

Este guia aborda pré-requisitos, registro, um exemplo de manipulador funcional, verificação, solução de problemas e quando uma plataforma gerenciada como TeleClaw faz mais sentido do que a auto-hospedagem.

Principais pontos

• Webhooks e long polling são mutuamente exclusivos. A configuração de um webhook desabilita getUpdates até que você o remova.
• HTTPS é obrigatório. Seu endpoint precisa de TLS 1.2+, um certificado correspondente e porta 443, 80, 88 ou 8443.
• Registre com setWebhook, verifique com getWebhookInfo. Verifique last_error_message quando as atualizações pararem de fluir.
• Use secret_token para confirmar que as requisições vêm do Telegram, não de scanners aleatórios atingindo sua URL.
• Alternativa sem código: TeleClaw lida com hospedagem e entrega para que você pule a camada do servidor inteiramente.

Webhooks vs long polling: qual escolher

O Telegram oferece duas maneiras de receber atualizações. De acordo com o FAQ de Bots, você escolhe um método por bot. Você não pode executar ambos ao mesmo tempo.

Long polling é a maneira mais rápida de prototipar. Seu bot chama getUpdates em um loop, processa cada lote e avança o offset. Sem domínio, sem certificado, sem porta aberta.

Webhooks invertem o modelo. O Telegram envia um POST HTTPS para sua URL sempre que alguém envia uma mensagem para o bot. Isso remove as requisições de polling ociosas e reduz o tempo de reação, o que é importante para bots de suporte, fluxos de pagamento e moderação de grupo em escala.

Se você ainda está registrando o próprio bot, comece com nosso guia para criar um bot do Telegram para obter um token do BotFather antes de continuar aqui.

Pré-requisitos para configuração de webhook de bot do Telegram

Antes de chamar setWebhook, confirme se sua infraestrutura atende aos requisitos do Telegram do guia oficial de webhooks:

• Token do bot do @BotFather (veja o guia de criação de bot linkado acima).
• Domínio público com um certificado TLS válido. Certificados autoassinados funcionam apenas se você carregar a chave pública via o parâmetro certificate.
• Porta suportada em seu servidor: 443 (padrão), 80, 88 ou 8443. Outras portas são rejeitadas.
• CN ou SAN do certificado deve corresponder ao domínio em sua URL de webhook. Certificados curinga podem não funcionar. Redirecionamentos não são suportados.
• Acesso POST de entrada das sub-redes do Telegram 149.154.160.0/20 e 91.108.4.0/22.

Para desenvolvimento local, exponha o localhost através de um túnel (ngrok, Cloudflare Tunnel ou similar) que lhe dê uma URL HTTPS pública. Teste se o túnel retorna HTTP 200 para requisições POST antes de registrar o webhook.

Passo 1: Construa seu endpoint de webhook

Seu servidor precisa de uma rota que aceite requisições POST, analise o objeto JSON Update e retorne HTTP 200 rapidamente. Manipuladores lentos fazem o Telegram tentar novamente e, eventualmente, relatar erros em getWebhookInfo.

Exemplo mínimo de Node.js com Express:

import express from 'express';

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

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // Process update.message, update.callback_query, etc.
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

Python com Flask segue o mesmo padrão: leia JSON da request, valide o cabeçalho secreto se configurado, processe a atualização, retorne 200.

Responda rápido. Trabalhos pesados (escritas em banco de dados, chamadas de API de IA) devem ir para uma fila em segundo plano. O Telegram espera um reconhecimento rápido. Você também pode responder inline retornando um corpo JSON com um campo method em vez de fazer uma chamada de API separada, conforme descrito nas notas de webhook da Bot API.

Passo 2: Configure o webhook do bot do Telegram com setWebhook

Assim que seu endpoint estiver ativo, registre-o com a Bot API. Substitua <TOKEN> e a URL pelos seus valores.

Usando curl:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

Referência de parâmetros:

• url (obrigatório): Seu endpoint HTTPS. Use uma string vazia para remover o webhook.
• secret_token (opcional): 1-256 caracteres (A-Z, a-z, 0-9, _, -). O Telegram o envia no cabeçalho X-Telegram-Bot-Api-Secret-Token.
• max_connections (opcional): 1-100 conexões simultâneas. O padrão é 40.
• allowed_updates (opcional): Limite quais tipos de atualização você recebe. Reduz o tamanho da carga útil se você apenas lida com mensagens.
• drop_pending_updates (opcional): Defina true para descartar atualizações em fila ao trocar webhooks.
• certificate (opcional): Carregue seu arquivo de chave pública para certificados autoassinados.

Uma resposta bem-sucedida se parece com {"ok":true,"result":true,"description":"Webhook was set"}.

Passo 3: Verifique com getWebhookInfo

Sempre confirme o registro imediatamente. Esta é sua primeira ferramenta de solução de problemas quando as atualizações param de chegar.

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

Exemplo de resposta:

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

Observe estes campos:

• url: Vazio significa que nenhum webhook está ativo (o bot está em long polling).
• pending_update_count: Atualizações em fila aguardando entrega. Um número crescente sinaliza falhas de entrega.
• last_error_date e last_error_message: O motivo da falha mais recente. Corrija a causa raiz, então o Telegram tenta novamente automaticamente.
• ip_address: Qual IP do Telegram está atualmente atingindo seu endpoint.

Envie uma mensagem de teste para seu bot de uma conta real do Telegram. Se pending_update_count permanecer em zero e os logs do seu servidor mostrarem o POST, a configuração do webhook do bot do Telegram está funcionando.

Exemplo de webhook de bot do Telegram: manipulador de solicitação de entrada

Bots de solicitação de entrada (fluxos de admissão estilo Guardião) precisam do tipo de atualização chat_join_request. Nosso guia de bot Guardião aborda o lado do produto. Aqui está a fiação do webhook.

Registre com solicitações de entrada habilitadas:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

Lógica do manipulador (pseudocódigo):

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // Execute a lógica de triagem, então aprove ou recuse via Bot API
 await approveChatJoinRequest(chat.id, from.id);
}

O Telegram entrega solicitações de entrada como atualizações push, então webhooks são um ajuste natural para bots de admissão que devem responder antes que a solicitação expire.

Remover webhook do bot do Telegram e voltar para polling

Precisa depurar localmente com getUpdates? Remova o webhook primeiro.

Opção A com deleteWebhook:

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

Opção B com setWebhook e URL vazia:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

Ambos os métodos reativam o long polling. Se você pular esta etapa, getUpdates não retorna nada porque o webhook ainda está registrado em sua URL de produção.

Solução de problemas comuns de erros de webhook

Quando getWebhookInfo mostra erros, combine a mensagem com uma correção:

Execute getWebhookInfo em um cronograma em produção. Capturar last_error_message cedo evita horas de perda silenciosa de mensagens.

Pule o servidor: bots gerenciados com TeleClaw

Nem todo bot precisa de infraestrutura de webhook personalizada. Se seu objetivo é um assistente de IA para um grupo ou canal de negócios, a hospedagem e a entrega de atualizações são problemas resolvidos.

TeleClaw conecta seu token do BotFather a um tempo de execução gerenciado alimentado por OpenClaw. Você configura personalidade, base de conhecimento e regras de moderação no painel. A plataforma lida com endpoints HTTPS, escalabilidade e roteamento de modelos de IA. Adicione @claw como administrador do grupo e entre no ar sem escrever um manipulador de webhook.

Explore o que um bot gerenciado pode fazer na página de recursos do TeleClaw. Para um passo a passo completo sem código, veja nosso guia de chatbot do Telegram sem código.

Webhooks personalizados ainda fazem sentido quando você precisa de controle total: backends proprietários, residência de dados regulamentada ou processamento de atualização não padrão. Para todo o resto, o custo operacional de gerenciamento de certificados, monitoramento e tratamento de novas tentativas aumenta rapidamente.

Conclusão

A configuração de webhook de bot do Telegram se resume a quatro etapas: implantar um endpoint HTTPS, chamar setWebhook, verificar com getWebhookInfo e monitorar erros. Use secret_token para validação de requisições, limite allowed_updates ao que você processa e mantenha os manipuladores rápidos.

Desenvolvedores que desejam entrega push de produção sem executar servidores podem usar TeleClaw em vez disso. Cole seu token, configure o comportamento da IA e concentre-se no que o bot diz, em vez de como as atualizações chegam.

Pronto para lançar um bot de IA sem gerenciar webhooks? Adicione @claw ao seu grupo do Telegram →