Você seguiu o tutorial certinho: criou o bot no @BotFather, copiou o token, configurou o webhook, testou uma vez e funcionou. No dia seguinte, silêncio. Cliente manda mensagem, bot não responde, e você fica sem saber se o problema é o token, a URL, o certificado ou o próprio servidor. Esse é um dos erros mais comuns — e mais mal documentados — de quem monta um bot de vendas ou atendimento no Telegram. Neste guia você vai entender exatamente onde o webhook costuma quebrar e como resolver cada caso, sem depender de tentativa e erro.
Por que o bot fica "mudo" mesmo com o token certo
O erro mais frequente não é o token em si, é a diferença entre token válido e webhook ativo. São duas coisas separadas: o token autentica seu bot na API do Telegram; o webhook diz ao Telegram para onde enviar cada mensagem nova. Um pode estar perfeito enquanto o outro está quebrado — e é exatamente isso que gera a sensação de "configurei tudo certo e não funciona".
Erro 1: token errado, revogado ou com espaço extra
Parece bobo, mas é a causa número um. Sintomas típicos:
- Resposta
401 Unauthorizedao chamar qualquer endpoint da API - Token copiado com quebra de linha ou espaço no início/fim (comum ao colar de um `.env` ou planilha)
- Token antigo ainda salvo no sistema depois de você gerar um novo com
/revokeno @BotFather
Resolução: rode https://api.telegram.org/bot<SEU_TOKEN>/getMe direto no navegador. Se voltar os dados do bot, o token está válido. Se voltar erro, gere um token novo no @BotFather e atualize em todos os lugares — inclusive em painéis de terceiros, porque é comum esquecer uma cópia salva em outro serviço.
Erro 2: webhook apontando para URL errada ou sem HTTPS
O Telegram só aceita webhook em URL HTTPS válida, porta 443, 80, 88 ou 8443. Erros comuns aqui:
- URL de teste (localhost, IP interno, domínio de staging) deixada em produção
- Barra final faltando ou sobrando, fazendo a rota cair em 404
- Registro DNS mudou (troca de servidor) e o webhook continua apontando para o IP antigo
Para checar, use getWebhookInfo — ele devolve a URL atual, quando foi o último erro e a mensagem exata de falha. É o primeiro comando que você deveria rodar sempre que o bot para de responder.
Erro 3: certificado SSL inválido ou autoassinado
Se seu servidor usa certificado autoassinado (comum em VPS configuradas na mão, sem Let's Encrypt), o Telegram recusa a conexão silenciosamente — o webhook fica "configurado" mas nunca entrega nada. Duas saídas:
- Trocar para um certificado válido de uma CA reconhecida (Let's Encrypt resolve isso de graça e renova sozinho)
- Se precisar mesmo usar autoassinado, enviar o certificado público junto na chamada
setWebhook— passo que muita gente esquece
Sinal claro desse erro no getWebhookInfo: campo last_error_message mencionando "SSL" ou "certificate verify failed".
Erro 4: webhook e getUpdates brigando entre si
Telegram não permite webhook e polling (getUpdates) ativos ao mesmo tempo para o mesmo bot. Se você testou localmente com polling e depois subiu o webhook em produção sem desligar o script de teste, os dois vão competir e nenhum funciona direito — ou pior, funciona pela metade, respondendo só parte das mensagens. Resolução: rode deleteWebhook antes de trocar de modo, e garanta que só existe um processo consumindo mensagens por vez.
Erro 5: servidor recebe a mensagem mas demora demais pra responder
O Telegram espera um 200 OK rápido do seu endpoint. Se o processamento (banco de dados lento, chamada externa travando, fila cheia) demorar além do timeout, o Telegram considera falha e tenta reenviar — o que pode gerar mensagens duplicadas ou respostas fora de ordem quando o bot volta a funcionar. A prática correta é responder 200 imediatamente e processar a lógica de negócio depois, de forma assíncrona, sem deixar o Telegram esperando.
Checklist rápido pra confirmar que o webhook está saudável
- Rodar
getMee confirmar que o token responde - Rodar
getWebhookInfoe conferir a URL, opending_update_counte olast_error_message - Testar a URL do webhook manualmente com uma requisição POST simulando o payload do Telegram
- Confirmar que não existe nenhum script antigo ainda rodando em modo polling
Se você gerencia mais de um bot, esse tipo de checagem manual não escala — é justamente o tipo de coisa que trava a operação quando um cliente reclama e ninguém percebeu a tempo. É por isso que ferramentas como o Telegram Inbox monitoram a saúde da conexão de cada bot automaticamente e avisam quando um webhook cai, em vez de você descobrir só quando um cliente reclama que mandou mensagem e não foi respondido. Depois que o bot está estável, vale também revisar como está o atendimento entre vários bots e como estruturar a gestão de vários canais ao mesmo tempo.
Perguntas frequentes
Por que o bot funcionou no teste e parou de funcionar depois?
Geralmente é queda de certificado (renovação que falhou), mudança de IP/domínio sem atualizar o webhook, ou um processo de polling antigo que voltou a rodar em paralelo. Comece sempre pelo getWebhookInfo.
Como sei se o problema é o token ou o webhook?
Se getMe falha, é o token. Se getMe funciona mas o bot não responde, é o webhook — parta para o getWebhookInfo.
Preciso de certificado pago para o webhook funcionar?
Não. Um certificado gratuito válido (Let's Encrypt, por exemplo) é suficiente. O problema é só com certificados autoassinados enviados sem o passo extra de upload.
O que é o campo pending_update_count e por que ele importa?
É o número de mensagens que o Telegram tentou entregar e não conseguiu. Se esse número está subindo, o webhook está fora do ar agora mesmo — é o primeiro sinal de alerta antes mesmo do cliente reclamar.
Dá pra ter vários bots com um único domínio de webhook?
Sim, desde que cada bot use um caminho (path) diferente na URL, para que seu servidor saiba identificar de qual bot veio cada mensagem.
Não deixe a configuração técnica travar a venda
Token, webhook e certificado são detalhes técnicos, mas o efeito de um erro nessa camada é 100% comercial: cliente manda mensagem, não recebe resposta, e some. Se você já perdeu venda por bot mudo, vale automatizar essa checagem em vez de depender de lembrar de testar toda semana. O Telegram Inbox, do Sincro PRO, conecta seus bots, monitora a conexão de cada um e centraliza as conversas — com planos a partir de R$19,90/mês e garantia de 7 dias. Teste agora e pare de descobrir que o bot está mudo só quando o cliente reclama.