Configurar o Trigger do WhatsApp

O primeiro nó do workflow é o gatilho que inicia a execução quando uma mensagem chega. Dependendo da API de WhatsApp que você usa, a configuração varia.

Para Evolution API (mais popular no Brasil)

# Configure na Evolution API o webhook para apontar para:
URL: https://seu-n8n.com/webhook/seu-id-aqui

# Método: POST
# Eventos: MESSAGES_UPSERT (mensagens recebidas)

# O payload chegará com esta estrutura:
{
  "event": "messages.upsert",
  "data": {
    "key": { "remoteJid": "5511999999999@s.whatsapp.net" },
    "message": { "conversation": "Olá, qual o preço do produto?" },
    "pushName": "João Silva"
  }
}

Criar o Nó AI Agent

No campo "Prompt", selecione "Take from previous node automatically" — o n8n vai pegar o texto da mensagem automaticamente. Configure o campo Session ID com uma expressão que usa o número do WhatsApp do remetente para identificar cada conversa:

# Para Evolution API — extrai o número do JID
{{ $json.data.key.remoteJid.replace('@s.whatsapp.net', '') }}

# Para Z-API — estrutura diferente
{{ $json.phone }}

Conectar o Chat Model

Clique no pino "Chat Model" do nó AI Agent e adicione:

• ✓ OpenAI Chat Model — configure sua API Key em Credentials. Recomendado: gpt-4o-mini para equilíbrio custo/qualidade ou gpt-4o para maior precisão
• ✓ Anthropic Claude — use claude-haiku-4-5 para velocidade e baixo custo, ou claude-sonnet-4-6 para raciocínio mais avançado
• ✓ Google Gemini — gratuito no tier básico, boa opção para começar sem custo de API

Escrever o System Prompt

O system prompt é a instrução permanente que define a personalidade, as regras e as capacidades do agente. É o componente mais importante — um bom system prompt transforma um modelo genérico em um atendente especializado.

Você é o assistente virtual da [Nome da Empresa], uma [tipo de negócio].
Seu nome é [Nome do Assistente].

PAPEL:
- Atender clientes com educação, objetividade e simpatia
- Responder dúvidas sobre produtos, preços, horários e políticas
- Qualificar leads e encaminhar para a equipe de vendas quando necessário

REGRAS:
- Responda SEMPRE em português brasileiro
- Use linguagem simples, sem jargões técnicos
- Mensagens curtas: máximo 3 parágrafos por resposta
- Não use markdown (negrito, itálico) — é WhatsApp, não e-mail
- Não invente informações que você não tem certeza
- Se não souber, diga claramente e ofereça alternativas

ESCALONAMENTO:
- Se o cliente pedir EXPLICITAMENTE para falar com humano → responda com a tag [ESCALAR]
- Se houver reclamação grave ou situação de urgência → use [ESCALAR]
- Nunca prometa o que não está no seu escopo

FERRAMENTAS DISPONÍVEIS:
- buscar_produto: Use para consultar preços e disponibilidade em tempo real
- verificar_pedido: Use quando o cliente informar um número de pedido
- consultar_agenda: Use para verificar horários disponíveis

DATA/HORA ATUAL: {{ $now }}
NOME DO CLIENTE: {{ $json.data.pushName }}

Configurar Memória Persistente

A memória permite que o agente lembre do contexto da conversa entre mensagens diferentes. Sem memória, cada mensagem é tratada como uma conversa nova — o cliente precisa repetir o contexto toda vez.

Configurar o Postgres Chat Memory

# Credenciais: conecte ao mesmo PostgreSQL do n8n

# Campo: Session ID
{{ $json.data.key.remoteJid.replace('@s.whatsapp.net', '') }}
# Isso cria um histórico separado por número de telefone

# Campo: Context Window Length
10  # Últimas 10 mensagens — bom equilíbrio memória/custo

# O n8n cria a tabela automaticamente na primeira execução
# Tabela: chat_message_history

Adicionar Ferramentas ao Agente

As ferramentas transformam o agente de um "respondedor de perguntas genéricas" em um assistente que realmente acessa dados do seu negócio em tempo real. O agente decide automaticamente quando chamar cada ferramenta baseado na descrição que você fornece.

Exemplo: Ferramenta de Consulta de Pedido

# Nome da ferramenta (o agente usa esse nome para decidir quando chamar)
verificar_pedido

# Descrição (MUITO IMPORTANTE — o agente lê isso para decidir quando usar)
"Use esta ferramenta quando o cliente informar um número de pedido 
e quiser saber o status, a previsão de entrega ou detalhes da compra. 
Input obrigatório: número do pedido (ex: 12345)"

# URL
https://sua-api.com/pedidos/{{ $fromAI('numero_pedido', 'número do pedido mencionado pelo cliente') }}

# Método: GET
# Autenticação: Bearer Token com sua chave de API

Configurar Escalonamento Humano

Um agente de IA sem escalonamento humano é incompleto. Sempre haverá situações que exigem um atendente real — reclamações graves, casos únicos, vendas complexas. O padrão mais eficaz é usar uma tag na resposta do agente como sinal de escalonamento.

# No nó If, verifique se a resposta do agente contém [ESCALAR]
{{ $json.output.includes('[ESCALAR]') }}

# Branch True: notificar atendente humano
# → Enviar mensagem para o WhatsApp do atendente com o histórico
# → Criar tarefa no CRM (HubSpot, Pipedrive, RD Station)
# → Enviar notificação no Slack ou Discord da equipe

# Branch False: enviar resposta normal do agente
# → Remover a tag [ESCALAR] da mensagem antes de enviar ao cliente

Enviar a Resposta ao WhatsApp

Para Evolution API

# URL
https://sua-evolution-api.com/message/sendText/nome-da-instancia

# Método: POST
# Headers: { "apikey": "sua-chave", "Content-Type": "application/json" }

# Body:
{
  "number": "{{ $('Webhook').first().json.data.key.remoteJid }}",
  "text": "{{ $json.output.replace('[ESCALAR]', '').trim() }}"
}

Para Z-API

# URL
https://api.z-api.io/instances/SUA_INSTANCE_ID/token/SEU_TOKEN/send-text

# Body:
{
  "phone": "{{ $('Webhook').first().json.phone }}",
  "message": "{{ $json.output }}"
}