Ferramentas

Telegram Bot API em 2026: do BotFather ao webhook seguro

Crie um bot no Telegram com a API oficial: token, getUpdates, webhook HTTPS, validação, segurança, limites e checklist de produção.

A Telegram Bot API é uma interface HTTP oficial para receber atualizações e enviar ações em nome de um bot. Você cria a identidade no BotFather, guarda o token como segredo e escolhe entre consultas com getUpdates ou webhook HTTPS.

A API é oferecida pelo Telegram, mas hospedagem, banco, observabilidade e serviços de IA podem gerar custo. Por isso retiramos a promessa “100% grátis” da versão anterior.

1. Crie o bot no BotFather

  1. abra a conversa oficial com @BotFather;
  2. use /newbot;
  3. defina nome e usuário;
  4. guarde o token fora do código e do chat de equipe;
  5. configure descrição, comandos e privacidade conforme o uso.

Se o token vazar, revogue e gere outro. Quem possui o token controla o bot.

2. Teste a API

As requisições usam o formato:

https://api.telegram.org/bot<TOKEN>/METHOD

Faça o primeiro teste por uma ferramenta que não registre o segredo em histórico público. O método getMe confirma a identidade. Depois envie uma mensagem ao bot e consulte atualizações.

3. Escolha polling ou webhook

getUpdates

É simples para desenvolvimento: o processo consulta novas atualizações e registra o último update_id. A documentação informa que atualizações não ficam armazenadas por mais de 24 horas.

Webhook

Em produção, o Telegram envia cada atualização ao endpoint HTTPS configurado. getUpdates e webhook são mutuamente exclusivos. Seu endpoint deve responder rápido e encaminhar o trabalho pesado para uma fila.

Webhook mínimo seguro

  • HTTPS válido e rota não previsível;
  • secret_token configurado e cabeçalho validado;
  • limite de tamanho e parser defensivo;
  • idempotência por update_id;
  • fila para tarefas lentas;
  • logs sem token nem conteúdo sensível;
  • retentativa controlada e fila de erro.

Estrutura de um serviço

Telegram → endpoint HTTPS → validação → fila → regras do bot
                                      ↘ banco / auditoria
                                      ↘ API externa

Responda ao Telegram antes de chamar um modelo de IA ou serviço lento. Caso contrário, timeouts podem gerar novas tentativas e mensagens duplicadas.

Grupos e privacidade

Em grupos, o bot só recebe o que suas configurações e permissões permitem. Não assuma que ele verá todas as mensagens. Para moderação, dê apenas as permissões necessárias e registre ações administrativas.

Bot com IA

Um modelo pode preparar respostas, mas o sistema precisa limitar tamanho, custo, conteúdo e ferramentas. Preserve uma mensagem de fallback e passagem para humano. Não envie automaticamente arquivo, comando administrativo ou dado privado apenas porque o texto do usuário pediu.

Checklist de produção

  • token em segredo e fora do repositório;
  • webhook validado com segredo;
  • processamento idempotente;
  • limites e retentativas tratados;
  • comandos e mensagens de erro claros;
  • política de retenção e exclusão de dados;
  • alerta para fila parada ou webhook rejeitado;
  • processo documentado para revogar o token.

Fontes oficiais

Revisão baseada na Telegram Bot API, no tutorial oficial e na introdução à plataforma. Em 30/08/2026, a documentação mostrava Bot API 10.3, publicada em 24/08/2026.