Como criar um bot de Telegram com n8n – Guia completo passo a passo

Como criar um bot de Telegram com n8n – Guia completo passo a passo

Neste artigo, você vai aprender como criar um bot de Telegram com n8n em 5 etapas: gerar token no BotFather, instalar n8n (Docker ou VPS), configurar webhook com URL pública e SSL, montar workflow com Telegram Trigger e Telegram Send Message, e testar com mensagens reais. O fluxo roda 100% self-hosted ou no n8n Cloud, com suporte a automação avançada via HTTP Request para APIs como OpenAI.

Neste guia, você vai do zero ao deploy de um bot funcional que recebe comandos e responde automaticamente, usando nodes nativos do n8n. Não precisa saber programar: tudo é feito por interface visual e configurações prontas.

Passo a passo para criar um bot de Telegram com n8n

Crie um bot de Telegram no n8n em até 20 minutos seguindo estas etapas: gere token no BotFather, instale n8n, configure webhook com URL pública e SSL, monte o workflow com nodes de trigger e resposta, e salve o fluxo. Abaixo, o resumo das etapas com tempo estimado e nível de dificuldade.

Etapa Descrição Tempo Dificuldade
1. Criar bot no BotFather Use o BotFather no Telegram para gerar token e definir comandos /start e /help. 5 min Fácil
2. Instalar n8n Escolha entre n8n Cloud (gratuito), Docker ou VPS (recomendado para produção). 10 min Médio
3. Configurar webhook Crie um node Webhook no n8n e insira URL pública com HTTPS (ex.: https://seusite.com/webhook). 7 min Médio
4. Montar workflow Adicione nodes Telegram Trigger, Function (opcional) e Telegram Send Message para responder mensagens. 8 min Fácil
5. Testar e salvar Envie /start no Telegram e verifique se o bot responde automaticamente. Salve o workflow. 5 min Fácil

Confira o guia completo do n8n em português para mais detalhes sobre nodes e configurações avançadas.

Dica de quem usa no dia a dia: Sempre salve o workflow antes de testar. O n8n não salva automaticamente, e você pode perder horas de configuração se esquecer.

Preparando o ambiente: instalação do n8n

Instale o n8n de três formas: n8n Cloud (gratuito, zero configuração), Docker (recomendado para self-hosted) ou VPS (Linux com Node.js). Escolha a opção que se adequa ao seu objetivo: testes rápidos ou produção escalável.

  • n8n Cloud: Acesse n8n.cloud e crie uma conta gratuita. Ideal para quem não quer lidar com servidor.
  • Docker: Execute docker run -it --rm --name n8n -p 5678:5678 n8nio/n8n para subir localmente. Use este guia para configurar em VPS.
  • VPS: Instale Node.js 18+ e execute npm install -g n8n. Para produção, use PM2 ou Docker para gerenciar o processo.

Confira a documentação oficial do n8n para detalhes de instalação em cada ambiente. Lá você encontra comandos específicos para AWS, Azure, DigitalOcean e outros.

Contexto técnico: O n8n Cloud usa um plano gratuito com limite de 1000 execuções/mês. Se passar disso, você precisa pagar ou migrar para self-hosted.

Criando e configurando o bot no Telegram

Crie um bot no Telegram usando o BotFather em 2 minutos: abra o app, pesquise por @BotFather, digite /newbot, dê um nome e um username (ex: meubot_do_n8n_bot), e copie o token gerado. Este token é a chave de acesso do seu bot à API do Telegram.

Depois, defina comandos básicos como /start e /help para guiar os usuários. Use o comando /setcommands no BotFather e envie a lista no formato:

start - Inicia o bot
help - Mostra ajuda


Como usar o BotFather: Nunca compartilhe o token do seu bot publicamente. Se vazar, o bot pode ser sequestrado ou usado para spam. Revogue o token com /revoke se necessário.

Para mais detalhes sobre webhooks, veja o guia sobre webhook no n8n.

Construindo o workflow: recebendo e respondendo mensagens

Para receber e responder mensagens no n8n, conecte Telegram Trigger → Function (opcional) → HTTP Request (para OpenAI) → Telegram Send Message. Cada node tem poucos campos; basta preencher o token, o chatId e o texto.

  • Telegram Trigger: Token (token do bot), Chat ID (identificador do usuário ou grupo), Update Type (message, callback_query).
  • Function: código JavaScript que formata a mensagem ou gera prompts.
  • HTTP Request: URL da API (ex.: https://api.openai.com/v1/completions), Headers (Authorization Bearer <chave>), Body (JSON com prompt).
  • Telegram Send Message: Chat ID (recebido no Trigger), Text (resposta final), Parse Mode (Markdown ou HTML).

Para usar a Evolution API dentro do workflow, veja Evolution API: o que é e como usar com n8n.

Curiosidade de quem usa no dia a dia: ao chamar a OpenAI, inclua “max_tokens”: 50 para evitar respostas longas que excedam o limite de 4096 bytes do Telegram.

Testando e depurando seu bot

Teste o bot ativando o modo “Execute Workflow” e analisando os logs de cada node. Se algo falhar, abra o console do n8n, procure a linha vermelha e ajuste o parâmetro.

  1. Abra o workflow e clique em “Execute Workflow”.
  2. Envie a mensagem /start no Telegram.
  3. Observe a execução na aba “Execution”.
  4. Se o webhook não receber a chamada, rode ngrok http 5678 e atualize a URL no Telegram.
  5. Corrija o erro indicado e repita até que a resposta apareça.

Para entender detalhes de depuração de webhooks, consulte documentação oficial do Telegram sobre webhooks.

Curiosidade de quem usa no dia a dia: o n8n grava a payload completa da chamada; copie‑a do log para reproduzir o erro em um sandbox.

Melhores práticas e dicas de escalabilidade

Proteja o token, limite a taxa e monitore a performance para escalar o bot sem interrupções. Use variáveis de ambiente para credenciais e configure alertas de uso.

  • Token seguro: armazene em process.env.TELEGRAM_TOKEN e nunca commit no repositório.
  • Limite de taxa: implemente Rate Limit node ou atrasos de setTimeout para não ultrapassar 30 msg/s.
  • Variáveis de ambiente: configure OPENAI_API_KEY e BASE_URL no Docker‑compose ou no PM2.
  • Monitoramento: habilite o painel de “Executions” do n8n e envie métricas para Grafana ou Datadog.
  • Backup: exporte o workflow JSON semanalmente e guarde em um bucket S3.

Curiosidade de quem usa no dia a dia: o n8n permite “Workflow Execution Timeout” de até 1 hora; ajuste quando usar APIs lentas como a da OpenAI.

Perguntas frequentes sobre como criar um bot de Telegram com n8n

Qual é a diferença entre usar um webhook e polling para receber mensagens do Telegram?

O webhook é mais eficiente: o Telegram envia atualizações automaticamente para uma URL configurada, enquanto o polling exige que o n8n fique constantemente verificando novas mensagens na API. O webhook é ideal para produção, pois reduz a latência e o uso de recursos.

Posso hospedar o bot de Telegram no n8n Cloud ou preciso de VPS?

Sim, o n8n Cloud (plano gratuito) suporta bots de Telegram, mas tem limite de 1000 execuções/mês. Para escalar ou usar recursos avançados, recomenda-se self-hosted em VPS com Docker ou Node.js.

É necessário usar Docker para rodar n8n ao criar um bot de Telegram?

Não é obrigatório. Você pode usar n8n Cloud, instalar via npm global ou até mesmo executar localmente. Docker é recomendado para produção por facilitar atualizações e isolamento de ambiente.

Como proteger o token do bot de Telegram no fluxo do n8n?

Armazene o token em variáveis de ambiente (ex: TELEGRAM_TOKEN) e nunca o commite no código. No Docker, use arquivos .env ou secrets do Swarm. No n8n Cloud, utilize as credenciais nativas da plataforma.

É possível integrar o bot de Telegram com ChatGPT usando n8n?

Sim! Use o node HTTP Request para chamar a API da OpenAI (ou ChatGPT) e processe a resposta com nodes como Function ou Set. Exemplo: receba uma mensagem no Telegram, envie para a OpenAI e devolva a resposta formatada ao usuário.

Qual a melhor forma de debugar erros de webhook no n8n?

Ative os logs detalhados no n8n, verifique a aba "Execution" após enviar uma mensagem e use ferramentas como ngrok para testar URLs locais. Copie a payload da falha e replique em um ambiente de sandbox para isolar o problema.

O n8n tem limite de mensagens por segundo no Telegram?

O Telegram permite até 30 mensagens por segundo por bot. Para evitar bloqueios, implemente um node de Rate Limit ou delays entre execuções. Monitore os logs para ajustar conforme a demanda.

Como escalar o bot de Telegram quando o número de usuários cresce?

Use self-hosted com recursos otimizados (CPU/RAM), implemente cache para respostas frequentes e distribua o fluxo em múltiplos workers. Monitore métricas como tempo de resposta e ajuste a infraestrutura conforme necessário.

🚀 Seu bot de Telegram está pronto para decolar!

Criar um bot de Telegram com n8n é mais simples do que parece: em poucas etapas você tem um assistente automatizado respondendo mensagens, processando comandos e até integrando com IA. O segredo está em começar pequeno, testar cada etapa e escalar com boas práticas de segurança e performance. Com este guia, você já tem tudo para colocar seu bot no ar hoje mesmo — seja para atendimento ao cliente, automação de tarefas ou até mesmo um assistente pessoal.

  • 5 minutos: Gere o token no BotFather e instale o n8n.
  • 10 minutos: Configure o webhook com SSL e monte o workflow básico.
  • 5 minutos: Teste com /start e ajuste conforme necessário.
  • Pronto! Seu bot está funcional e pode ser expandido com integrações avançadas.

Agora que seu bot está funcionando, que tal explorar mais automações com n8n? Confira nossos tutoriais sobre integrações com APIs ou automação para negócios para levar suas habilidades ao próximo nível!

Quer mais sobre o assunto? Veja todos os artigos de n8n ou a lista completa de artigos.