AI agent on WhatsApp with n8n: a complete step-by-step guide

The design has six nodes. Webhook (trigger) receives the instance's messages event. A Code node extracts number, text and id and drops your own messages. An IF or the Code node itself cuts duplicates and conversations already with a human. The AI Agent node takes the text, uses that contact's memory and, if needed, calls tools. Finally, an HTTP Request (or the community node) sends the reply through send/text.

Before building, understand what n8n delivers and what it does not: it orchestrates, but the AI model belongs to the provider you set in the node's credential, and that provider's cost is separate. The n8n integration page and the guide to integrating WhatsApp with n8n cover the basics; here the focus is the agent.

A ZapZap instance connected by QR code, the API key and secret, an n8n reachable from the internet (self-hosted with HTTPS or n8n Cloud) and a credential for an AI model provider. For local tests, n8n needs a public URL; a tunnel works for development, not for production.

In n8n, create a Header Auth credential or use fixed header fields for x-api-key and x-api-secret. That way the secret lives in the credential, not written into every node. If you prefer to start from something ready, there are templates in n8n templates for WhatsApp.

Add a Webhook node, POST method, and copy the Production URL (the test URL only works while the flow is listening). Register that URL on the instance with POST /webhook, enabling the messages event. Activate the flow before using the production URL.

Test with POST /instances/{id}/webhook/test: it fires a test event and returns your endpoint's HTTP status and response time. If something fails, GET /instances/{id}/webhook/deliveries shows the latest deliveries and GET /webhook/errors the failures.

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"]}'

This is the node that prevents the three most common bugs: the agent replying to its own message (fromMe), replying twice to the same event and replying in groups by accident. Check the exact event structure in the Webhook's execution tab with a real message; the code reads defensively and you adjust the names.

The node returns one item with numero, texto and id. If the message should not be handled, it returns an empty list, which ends the flow on that branch. Deduplication uses the workflow's static storage, enough for a single n8n; with several n8n instances, use a database or 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 } }];

Add the AI Agent node. Configure three things. Chat model: pick the provider and model in the credential (the model name lives in your configuration, not in this guide). Memory: use a window memory with the session key equal to the contact's number, so each customer has their own conversation. System prompt: role, tone, limits and the rule for handing off to a human.

A working system prompt, in a few lines: who the assistant is and which company it is for; reply in short messages, in a WhatsApp tone; use only the information provided; if you do not know or the customer asks for a person, reply with exactly the agreed handoff sentence. That fixed sentence lets the flow detect the handoff right after, with an IF node.

If the agent needs to look up data (schedule, order, stock), add tools: an HTTP Request as a tool pointing to your system, with a clear description of what it does. Keep tools few and well described; models make more mistakes when they have many options.

After the agent, add an HTTP Request. Method POST; URL https://api.zapzapapi.com/api/v1/YOUR_INSTANCE_ID/send/text; headers x-api-key and x-api-secret; JSON body with number and text. The text field comes from the agent's output, and number comes from the Code node.

The delay field on send/text and the typing presence (message/presence) make the reply feel more natural, and a small delay keeps it from looking like a machine. Use them moderately: what weighs most for the number is overall behavior, not a sending trick.

{
  "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}'

There is a community node package, n8n-nodes-zapzap, published on npm (version 0.1.3 checked on 10/27/2026), covering message and media sending, polls, buttons and lists, reactions, instance management and real-time event reception. It simplifies setup because the node already knows the fields.

One important limit: according to n8n's documentation (read on 10/27/2026), unverified community nodes are not available on n8n Cloud and require self-hosted n8n. Since this is a community package and we do not have n8n's verified badge, the guaranteed path on n8n Cloud is HTTP Request. Both work with the same API and the same credentials.

n8n-nodes-zapzap

After the agent, an IF node checks whether the reply is the handoff sentence. If it is, the flow marks the contact as with a human (in an n8n table, Redis or your CRM), notifies the team and sends the customer a short message. Before the agent, another IF checks that mark and ends the flow if the contact is with a human.

The mark needs an expiry or a release button, otherwise the contact never goes back to the bot. The same design appears in the guide to the WhatsApp AI chatbot, with handoff rules and cost.

For day to day, keep n8n's execution history on for the first few days, review sample conversations and tune the prompt. To see all the API features the agent can use as a tool, open the reference and the OpenAPI file.