Agente de IA no WhatsApp com n8n: passo a passo completo

O desenho tem seis nós. Webhook (gatilho) recebe o evento messages da instância. Um nó Code extrai número, texto e id e descarta mensagens suas. Um IF ou o próprio Code corta duplicatas e conversas já com humano. O nó AI Agent recebe o texto, usa a memória daquele contato e, se precisar, chama ferramentas. Por fim, um HTTP Request (ou o nó da comunidade) envia a resposta por send/text.

Antes de montar, entenda o que o n8n entrega e o que não entrega: ele orquestra, mas o modelo de IA é do provedor que você configurar na credencial do nó, e o custo desse provedor é separado. A página da integração com n8n e o guia de integrar WhatsApp no n8n cobrem a base; aqui o foco é o agente.

Uma instância do ZapZap conectada por QR code, a chave e o segredo da API, um n8n acessível pela internet (self-hosted com HTTPS ou n8n Cloud) e uma credencial de um provedor de modelo de IA. Para testes locais, o n8n precisa de uma URL pública; túnel serve para desenvolver, mas não para produção.

Crie no n8n uma credencial Header Auth ou use campos fixos de cabeçalho para x-api-key e x-api-secret. Assim o segredo fica na credencial, não escrito em cada nó. Se preferir partir de algo pronto, há modelos em templates de n8n para WhatsApp.

Adicione um nó Webhook, método POST, e copie a Production URL (a de teste só funciona com o fluxo em modo de escuta). Registre essa URL na instância com POST /webhook, ativando o evento messages. Ative o fluxo antes de usar a URL de produção.

Teste com POST /instances/{id}/webhook/test: ele dispara um evento de teste e devolve o status HTTP e o tempo de resposta do seu endpoint. Se algo falhar, GET /instances/{id}/webhook/deliveries mostra as últimas entregas e GET /webhook/errors, as falhas.

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"url":"https://SEU-N8N.com/webhook/whatsapp-agente","enabled":true,"events":["messages"]}'

Este é o nó que evita os três bugs mais comuns: o agente responder à própria mensagem (fromMe), responder duas vezes ao mesmo evento e responder em grupos sem querer. A estrutura exata do evento deve ser conferida na aba de execução do Webhook, com uma mensagem real; o código usa leitura defensiva e você ajusta os nomes.

O nó devolve um item com numero, texto e id. Se a mensagem não deve ser tratada, devolve uma lista vazia, o que encerra o fluxo naquele ramo. A deduplicação usa o armazenamento estático do workflow, suficiente para um n8n único; com várias instâncias do n8n, use um banco ou Redis.

const evento = $input.first().json.body ?? $input.first().json;
const msg = evento.message ?? evento.data ?? evento;

if (msg.fromMe) return [];
const id = msg.messageid ?? msg.id;
const numero = msg.sender ?? msg.from;
const texto = msg.text ?? msg.body ?? "";
const grupo = String(msg.chatid ?? msg.chatId ?? "").endsWith("@g.us");

if (!numero || !texto || grupo) return [];

const estado = $getWorkflowStaticData("global");
estado.vistos = estado.vistos ?? [];
if (id && estado.vistos.includes(id)) return [];
if (id) estado.vistos = [...estado.vistos.slice(-500), id];

return [{ json: { numero: String(numero).replace(/\D/g, ""), texto, id } }];

Adicione o nó AI Agent. Configure três coisas. Modelo de chat: escolha o provedor e o modelo na credencial (o nome do modelo fica na sua configuração, não neste guia). Memória: use uma memória de janela com a chave de sessão igual ao número do contato, para cada cliente ter a sua própria conversa. Prompt de sistema: papel, tom, limites e regra de passagem para humano.

Um prompt de sistema funcional, em poucas linhas: quem é o assistente e para qual empresa; responda em mensagens curtas, no tom de WhatsApp; use apenas as informações fornecidas; se não souber ou se o cliente pedir uma pessoa, responda exatamente a frase de transferência combinada. Essa frase fixa permite que o fluxo detecte o handoff logo depois, com um nó IF.

Se o agente precisar consultar dados (agenda, pedido, estoque), adicione ferramentas: um HTTP Request como ferramenta apontando para o seu sistema, com descrição clara do que faz. Mantenha poucas ferramentas e bem descritas; modelos erram mais quando têm muitas opções.

Depois do agente, adicione um HTTP Request. Method POST; URL https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/send/text; cabeçalhos x-api-key e x-api-secret; corpo JSON com number e text. O campo text vem da saída do agente, e number vem do nó Code.

O campo delay do send/text e a presença digitando (message/presence) deixam a resposta mais natural, e um pequeno atraso evita parecer máquina. Use com moderação: o que mais pesa para o número é o comportamento geral, não um truque de envio.

{
  "number": "{{ $('Normalizar').item.json.numero }}",
  "text": "{{ $json.output }}",
  "delay": 2000
}

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/send/text \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"number":"5511999999999","text":"Resposta do agente","delay":2000}'

Existe um pacote de nós da comunidade, n8n-nodes-zapzap, publicado no npm (versão 0.1.3 conferida em 27/10/2026), que cobre envio de mensagens, mídia, enquetes, botões e listas, reação, gestão de instâncias e recebimento de eventos em tempo real. Ele simplifica a configuração, porque o nó já conhece os campos.

Um limite importante: segundo a documentação do n8n (lida em 27/10/2026), nós da comunidade não verificados não estão disponíveis no n8n Cloud e exigem n8n self-hosted. Como este pacote é da comunidade e não temos o selo de verificado do n8n, o caminho garantido no n8n Cloud é o HTTP Request. Os dois funcionam com a mesma API e as mesmas credenciais.

n8n-nodes-zapzap

Depois do agente, um nó IF verifica se a resposta é a frase de transferência. Se for, o fluxo marca o contato como com humano (em uma tabela do n8n, Redis ou no seu CRM), avisa a equipe e envia ao cliente uma mensagem curta. Antes do agente, outro IF consulta essa marca e encerra o fluxo se o contato estiver com humano.

A marca precisa de um prazo de expiração ou de um botão de liberar, senão o contato nunca volta ao bot. Esse mesmo desenho aparece no guia de chatbot de WhatsApp com IA, com regras de handoff e custo.

Para o dia a dia, mantenha o histórico de execuções do n8n ligado nos primeiros dias, revise amostras de conversa e ajuste o prompt. Para ver todos os recursos da API que o agente pode usar como ferramenta, abra a referência e o OpenAPI.