Tutorial de bot do Telegram com n8n: crie um chatbot de IA

Nesta seção, vamos criar um assistente de IA no Telegram: o usuário envia uma mensagem ao bot, o n8n usa IA para responder e mantém o histórico da conversa de cada usuário.

[Telegram Trigger] ─▶ [AI Agent] ─▶ [Telegram: Send Message]
                        ├ Chat Model
                        └ Memory (separada por ID do usuário)

1. Crie um bot do Telegram

1. Pesquise @BotFather no Telegram.
2. Envie /newbot.
3. Siga as instruções para informar o nome de exibição do bot e um nome de usuário que termine em bot (por exemplo, my_helper_bot).
4. O BotFather retornará um Bot Token. Guarde-o com segurança e não o compartilhe.

2. Crie uma credencial

No n8n, adicione uma credencial Telegram API e cole o Bot Token.

3. Telegram Trigger

Crie um fluxo de trabalho e selecione Telegram Trigger como primeiro nó:

• Trigger On: Message

O Telegram Trigger usa um Webhook para receber mensagens. Portanto:

• O n8n precisa estar acessível pela internet usando HTTPS (consulte Hospedagem própria).
• Para testes locais, você pode expor o serviço temporariamente usando ferramentas como o Cloudflare Tunnel.

Clique em Listen for test event e envie uma mensagem ao seu bot pelo Telegram. O nó receberá dados parecidos com estes:

{
  "message": {
    "message_id": 42,
    "from": { "id": 123456789, "first_name": "João" },
    "chat": { "id": 123456789, "type": "private" },
    "text": "Olá"
  }
}

Um bot só pode ter um Webhook configurado. Ao alternar o mesmo bot entre um fluxo de teste e um fluxo de produção, o último que for ativado ficará em vigor.

4. AI Agent

Adicione um nó AI Agent:

• Source for Prompt: Define below
• Prompt (User Message): {{ $json.message.text }}
• System Message:

Você é um assistente simpático do Telegram chamado “Ajudante”.
Responda em português brasileiro, de forma concisa e adequada para leitura no celular.

Conecte um Chat Model (OpenAI ou um modelo local do Ollama).

5. Mantenha o contexto por usuário

Adicione Simple Memory (para uso em produção, recomendamos Postgres / Redis Chat Memory):

• Session ID: Define below
• Key: {{ $('Telegram Trigger').item.json.message.chat.id }}

Use o chat ID como Session Key para que cada usuário (ou grupo) tenha sua própria memória de conversa, sem misturar as conversas.

6. Envie uma resposta

Adicione um nó Telegram com a operação Send Message:

• Chat ID: {{ $('Telegram Trigger').item.json.message.chat.id }}
• Text: {{ $json.output }}

A resposta do AI Agent fica no campo output.

Em Additional Fields, você pode configurar Parse Mode. Se a resposta do modelo contiver símbolos Markdown que causem falha no envio, deixe Parse Mode sem configuração e envie o texto sem formatação.

7. Teste e publique

1. Clique em Execute workflow e envie uma mensagem ao bot para testá-lo.
2. Quando tudo estiver funcionando, clique em Save e Publish.

Recursos avançados

Permita apenas usuários específicos

Adicione um nó If depois do Telegram Trigger:

{{ $json.message.from.id }} equals 123456789

Envie os casos que não corresponderem por outro caminho para responder “Este bot é apenas para uso interno” ou simplesmente ignorá-los. Você também pode limitar os IDs de usuário nas configurações do Telegram Trigger (dependendo da versão). Encontre seu próprio ID nos dados recebidos pelo Trigger.

Processe comandos

Use um nó Switch para direcionar o fluxo de acordo com o conteúdo da mensagem:

Processe mensagens que não sejam texto

Quando o usuário envia uma imagem, figurinha ou mensagem de voz, message.text fica vazio. Antes do AI Agent, use If para verificar se {{ $json.message.text }} existe e evitar erros.

Para processar imagens: use Get File no nó Telegram para baixar a imagem e, em seguida, envie-a para análise por um modelo com suporte a visão.

Adicione ferramentas

Conecte a esse Agent as ferramentas apresentadas em Introdução ao AI Agent, como Google Sheets, HTTP Request e calculadora. Assim, o bot poderá consultar dados e executar ações.

Envie mensagens proativamente

Além de responder a mensagens, qualquer fluxo de trabalho pode usar o nó Telegram para enviar mensagens proativamente a você, como relatórios diários, alertas de erro e notificações de pedidos. Basta saber seu Chat ID.

Atualizado 12 de outubro de 2026