Como criar um agente WhatsApp no n8n com Evolution API

Tutorial do zero para montar um agente que recebe mensagens do WhatsApp, envia para um modelo de IA no n8n e responde pelo mesmo número usando a Evolution API.

Cenário usado neste guia

Arquitetura final

O fluxo terá três partes: WhatsApp conectado na Evolution API, webhook do n8n recebendo mensagens e um agente de IA gerando a resposta.

n8n https://n8ned.edsystems.com.br/
Evolution API https://evolapi.edsystems.com.br
Instância WhatsApp eduteste
Modelo de IA Gemini, Groq ou outro provider configurado no n8n
Nunca coloque API keys diretamente em nós de código ou mensagens. Use credenciais do n8n ou variáveis de ambiente.

1. Preparar a Evolution API

  1. Acesse o painel da Evolution API em https://evolapi.edsystems.com.br/manager.
  2. Confirme que a instância eduteste existe.
  3. Confirme que o status da instância está conectado ou open.
  4. Se a instância não estiver conectada, escaneie o QR Code com o WhatsApp antes de continuar.

Para o workflow funcionar, o nome da instância precisa bater exatamente com o nome usado no nó de envio do n8n:

eduteste

2. Criar o workflow no n8n

  1. Acesse https://n8ned.edsystems.com.br/.
  2. Clique em New Workflow.
  3. Dê um nome claro, por exemplo: Agente WhatsApp - eduteste.
  4. Salve o workflow antes de criar o webhook de produção.
O webhook de produção só fica estável quando o workflow está salvo e ativo.

3. Criar o nó Webhook

Adicione um nó Webhook como início do fluxo.

Campo Valor recomendado
HTTP Method POST
Path Um identificador único, por exemplo agente-eduteste
Response Mode Immediately

Depois de salvar e ativar o workflow, a URL de produção ficará parecida com:

https://n8ned.edsystems.com.br/webhook/agente-eduteste

4. Configurar o webhook na Evolution

No painel da Evolution API, abra a instância eduteste e configure o webhook.

Campo Valor
Webhook URL https://n8ned.edsystems.com.br/webhook/agente-eduteste
Enabled true
Events MESSAGES_UPSERT
Webhook by events false, a menos que queira URLs separadas por evento
Se a Evolution apontar para uma URL antiga, o n8n vai receber 404 ou o fluxo nem será acionado.

5. Separar os dados recebidos

Depois do Webhook, adicione um nó Set, chamado Coleta, para organizar os campos principais.

Campo Expressão
nome {{ $json.body.data.pushName }}
telefone {{ $json.body.data.key.remoteJid }}
tipo {{ $json.body.data.messageType }}
mensagem {{ $json.body.data.message.conversation }}

Para mensagens simples de texto, o campo mais importante é mensagem.

6. Filtrar somente mensagens de texto

Adicione um nó Switch chamado Verifica tipo de arquivo.

Crie uma regra para seguir apenas quando:

{{ $('Recebe mensagem').item.json.body.data.messageType }} == conversation

Com isso, o agente responde mensagens de texto primeiro. Depois você pode criar rotas para áudio, imagem e documento.

7. Criar o agente de IA

Adicione o nó AI Agent do LangChain no n8n.

Campo Valor
Prompt Type Define
Text {{ $json.mensagem }}
System Message O prompt do personagem e regras do atendimento

Exemplo de system prompt simples

Você é um atendente virtual no WhatsApp.
Responda com clareza, em português do Brasil.
Faça uma pergunta por vez.
Nunca invente informações.
Quando não souber algo, peça para um humano assumir.
Mantenha respostas curtas e adequadas para WhatsApp.

Memória da conversa

Adicione o nó Simple Memory e conecte no agente. Use o telefone como chave de sessão:

{{ $('Coleta').item.json.telefone }}

Modelo de chat

Adicione um modelo, como Google Gemini Chat Model ou Groq Chat Model, e conecte no agente.

Configure a API key na área de credenciais do n8n, não dentro do prompt.

8. Separar respostas longas em partes

Para WhatsApp, respostas muito longas ficam ruins. Uma prática simples é pedir ao agente para separar blocos com uma barra invertida e depois quebrar isso em itens.

Adicione um nó Code depois do agente:

const texto = $input.first().json.output || "";

const itens = texto
  .split(/\\/)
  .map(item => item.trim())
  .filter(Boolean);

return itens.map(item => ({ json: { item } }));

Depois use um nó Loop Over Items e opcionalmente um Wait de 1 segundo entre mensagens.

9. Enviar resposta para o WhatsApp

Adicione o nó Evolution API, operação de envio de texto.

Campo Valor correto
Credential Credencial da Evolution apontando para https://evolapi.edsystems.com.br
Resource messages-api
Operation send-text
Instance Name eduteste
Remote JID {{ $('Recebe mensagem').item.json.body.data.key.remoteJid }}
Message Text {{ $json.item }}
Não use {{ $('Recebe mensagem').item.json.body.instance }} no campo Instance Name se você quer forçar o uso de eduteste. Payload antigo pode trazer outro nome de instância e quebrar o envio.

10. Ativar e testar

  1. Salve o workflow.
  2. Ative o workflow.
  3. Confira se a Production URL do webhook está registrada na Evolution.
  4. Envie uma mensagem para o WhatsApp conectado na instância eduteste.
  5. Abra Executions no n8n e veja se todos os nós ficaram verdes.

Se quiser testar o webhook sem WhatsApp, envie um POST de teste com um payload parecido com o da Evolution. O teste seco valida o n8n, mas não garante envio real pelo WhatsApp.

Checklist de erro comum

Erro Causa provável Correção
Erro ao enviar mensagem de texto Instância errada ou inexistente Fixar Instance Name como eduteste
404 webhook Workflow inativo ou URL antiga na Evolution Ativar workflow e atualizar webhook na Evolution
Authorization failed Credencial Evolution errada Revisar credencial no n8n sem expor a chave
n8n mostra URL localhost WEBHOOK_URL ausente Configurar WEBHOOK_URL=https://n8ned.edsystems.com.br/
Alerta X-Forwarded-For n8n atrás de proxy sem trust proxy Configurar N8N_PROXY_HOPS=1

Fluxo final esperado

  1. Recebe mensagem recebe o webhook da Evolution.
  2. Coleta extrai nome, telefone, tipo e texto.
  3. Verifica tipo de arquivo deixa passar mensagem de texto.
  4. AI Agent gera resposta com memória.
  5. Code separa resposta em partes.
  6. Loop Over Items envia uma mensagem por vez.
  7. Envia mensagem para o WhatsApp responde pela Evolution usando eduteste.