Telegram Bot API

Verificador de webhook de bot do Telegram

Verifique o webhook do seu bot do Telegram com um clique: a ferramenta chama getWebhookInfo, mostra a URL, as atualizações pendentes e o último erro de entrega com uma dica de como corrigi-lo, e permite configurar ou apagar o webhook.

O token fica no seu navegador (localStorage) e é enviado apenas para api.telegram.org.

Configurar ou alterar o webhook

Como verificar o webhook de um bot do Telegram

  1. Cole o token do bot. Marque Servidor de testes se o bot estiver no ambiente de testes.
  2. Clique em Verificar webhook. Você recebe um de três resultados: nenhum webhook (o bot usa getUpdates), um webhook sem erros nas últimas 24 horas ou um problema de entrega com a hora e o texto do último erro, além de uma dica.
  3. Confira o contador de atualizações pendentes. Acima de 100 ele fica destacado: as atualizações estão se acumulando porque o seu servidor não as aceita.
  4. Abaixo aparece a resposta completa do getWebhookInfo: url, has_custom_certificate, pending_update_count, last_error_date, last_error_message, max_connections e outros campos.
  5. Para alterar, abra Configurar ou alterar o webhook: informe uma URL HTTPS e um secret_token opcional, escolha se quer descartar as atualizações pendentes e clique em setWebhook ou deleteWebhook. A verificação roda de novo automaticamente.

Erros comuns de webhook

A dica é escolhida a partir do texto de last_error_message:

O erro se parece comO que verificar
SSL / certificateUm certificado válido para o domínio (ou um autoassinado enviado pelo parâmetro certificate do setWebhook), TLS 1.2+.
Wrong response from the webhook: 4xx/5xxO caminho, a verificação do seu secret_token e os erros do servidor — o Telegram espera 2xx.
Timeout / connection resetO servidor precisa ser acessível pela internet na porta 443, 80, 88 ou 8443 e responder rápido.
Connection refusedNada escuta na porta, ou um firewall bloqueia o Telegram.
Host can't be resolvedOs registros DNS do domínio do webhook.

O formulário envia apenas url, secret_token e drop_pending_updates. O segredo (1–256 caracteres A-Z a-z 0-9 _ -) chega no cabeçalho X-Telegram-Bot-Api-Secret-Token de cada requisição. Para allowed_updates, max_connections ou um certificado, use o /pt/telegram-bot-api-tester.html#setWebhook.

Privacidade

O token fica no localStorage do seu navegador, e getWebhookInfo, setWebhook e deleteWebhook são enviados direto para api.telegram.org — nada passa pelo nosso servidor. A mesma chamada está disponível no /pt/telegram-bot-api-tester.html#getWebhookInfo. Um passo a passo completo de configuração está em /pt/guides/telegram-bot-webhook.html, e o 409 Conflict e outros erros são explicados em /pt/guides/telegram-bot-api-errors.html.

Perguntas frequentes

Como saber se o meu bot do Telegram tem webhook?

Chame getWebhookInfo. Se url estiver vazia, não há webhook configurado e o bot funciona com getUpdates. O verificador acima faz essa chamada por você e explica o resultado.

Como apagar o webhook de um bot do Telegram?

Chame deleteWebhook — na ferramenta, abra Configurar ou alterar o webhook e clique em deleteWebhook. Marque Descartar atualizações pendentes apenas se quiser descartar as atualizações na fila. Depois disso, o getUpdates volta a funcionar.

Por que o pending_update_count não para de crescer?

O Telegram não consegue entregar as atualizações: o seu servidor está inacessível, lento ou responde com um status fora de 2xx. Veja o last_error_message; o Telegram continua tentando, e as atualizações ficam guardadas por até 24 horas.

O que significa "Wrong response from the webhook"?

O seu servidor respondeu com um status HTTP diferente de 2xx, por exemplo 404 por um caminho errado ou 500 por uma falha. O Telegram espera uma resposta 2xx rápida e, caso contrário, tenta de novo.

Outros utilitários

Localizador de chat IDEscape de MarkdownV2 e HTMLValidador de initData do Mini AppBot API Tester