n8n WhatsApp AI Agent: How We Build Them for Production

What do you need to build a WhatsApp AI agent in n8n?

Which WhatsApp connection to use is a business decision with real consequences for cost and account risk. We build on both and recommend one per project. We wrote a separate, sourced comparison: Evolution API vs WhatsApp Cloud API. The rest of this page applies to either.

One practical note if you choose Evolution API: its n8n node is a community node, and n8n's docs say "unverified community nodes aren't available on n8n cloud and require self-hosting n8n" (source). Plain HTTP Request nodes against Evolution's REST API work anywhere.

How do you give an n8n WhatsApp agent memory per customer?

Use the Postgres Chat Memory node with a custom session key. Ours is built from the Evolution instance ID and the customer's WhatsApp ID, so one n8n instance can serve several numbers without histories colliding. The main agent keeps a window of the last 30 exchanges.

Two rules we learned:

1. Give every agent its own key. Our live builds have a router agent and a main agent sharing one key, so the router's one-word answers end up in the main agent's history. It adds noise to the context. The templates below use a separate _router key.
2. Put facts in tools, not memory. Memory is for the conversation. Menus, prices and hours live in the database or the prompt, where you can change them without touching anyone's history.

How does the agent read your menu, catalog or prices?

Through tools. Our main agents each have seven:

• Vector search over the knowledge base: top 25 chunks, reranked by Cohere down to 5
• List documents, including the column schema of any spreadsheet that was imported
• Get file contents, for when a whole document beats a chunk
• Query rows, a Postgres tool that runs SQL over spreadsheet rows stored as JSONB, which keeps prices exact
• Date & Time, so "are you open now?" has a correct answer
• Menu images, a code tool that returns the image URLs the agent may choose to send
• one business-specific tool: a payment QR image for one client, the shop's location for the other

The knowledge half began as Cole Medin's public Ultimate n8n Agentic RAG Template. We adapted it for WhatsApp rather than reinventing it.

For tools that take arguments, n8n's $fromAI() lets the model fill them. Our order notification tool uses it for items, amount, payment method, contact and address, and passes the WhatsApp instance and message ID from the webhook directly, so the model cannot get those wrong.

The main agent returns structured JSON: reply text, a message type (default, pre_order_confirmation, post_order_confirmation) and an optional list of image URLs. A Switch node routes on the type. That one decision keeps the workflow readable: the model decides what is happening, and plain nodes decide what to send.

How do you hand off a WhatsApp chat to a human in n8n?

A large share of the nodes in our builds go here. The pattern:

1. A status per chat in Postgres: ai_active or human_chat (one build adds pending_human_transfer).
2. A router agent returns one of those values. In the newer build it goes through a Structured Output Parser. Its prompt lists when to escalate (asks for a person, complaint, refund, wrong order, payment dispute) and, just as important, when not to: anything that looks like an order stays with the AI, even "2 large, 1 small".
3. On escalation, set the status, tell the customer a person is coming and how to come back ("type ai"), and post the customer's message to a staff WhatsApp group, quoted.
4. While the status is human, the AI stays quiet unless the customer asks for it back.
5. Staff replies count. With Evolution API, a reply typed on the business phone arrives as a message from the business itself. We treat that as a handoff, so staff never have to switch the bot off.
6. A schedule resets stale handoffs. Every 30 minutes, chats in human mode with no update for 30 minutes go back to the AI.
7. Optional confirm step. Ask "want a person? type yes" before transferring. It keeps staff from getting chats a rephrased question would have solved.

How do you handle WhatsApp voice notes in n8n?

Check the message type in a Switch. For audio, fetch the media as base64 from the gateway, convert it to a file with Convert to File, and call the OpenAI node's transcribe operation. We set the language to Urdu for our clients. The transcript then goes to the same agent as text.

To answer by voice, run the reply through a small formatter agent first. Ours strips WhatsApp formatting, turns lists into sentences, spells prices out as words and converts Roman Urdu into Urdu script so the voice pronounces it properly. Then call a text to speech API (Uplift AI in our builds, for Urdu) and send the audio back through the gateway. Keep order summaries as text; people want to read those.

What breaks in production, and how do you handle it?

• Sends fail. The reply send nodes in our builds retry up to 5 times, 2 seconds apart. The main agent retries the same way. A customer who gets no reply assumes nobody is there.
• Models break JSON. They wrap it in code fences, or print it twice. Our parser strips fences and reads only the first complete JSON block, tracking brackets and strings.
• Models break WhatsApp formatting. WhatsApp bold is a single asterisk, and asterisk bullets collide with it. Our prompts spell out the rules with a bad and a good example of a menu item.
• Group chats. The newer build filters group messages at the door, so staff talking in the escalation group never reach the agent.
• Errors nobody sees. Neither live workflow has an n8n error workflow yet, so failures that survive retries sit in the execution log. Add one that alerts the staff group. It is our next change.
• Secrets in nodes. Keep API keys in n8n credentials, never in node parameters. Exported workflows get shared, pasted into tickets and committed. Our templates use a Header Auth credential for the gateway key.

Where do we host it?

n8n and Evolution API run self-hosted on a server managed with Easypanel. Postgres, pgvector and the menu images live on Supabase. Self-hosting is what makes the community node possible and means there is no per-execution bill; if you would rather not run servers, see how the platforms compare in n8n vs Zapier vs Make.

Get the templates

We are turning two patterns from these builds into importable n8n templates, with every client detail, credential and URL removed:

• WhatsApp AI agent with human handoff: webhook, filters, chat state table, router agent, main agent with Postgres memory and a catalog tool, staff alert, and the 30 minute reset. 29 nodes.
• WhatsApp voice notes in, voice replies out: transcription, answer, speech rewrite, text to speech and audio send. 19 nodes.

We will publish both on GitHub and in the n8n template library. Until then, ask us for the JSON through the enquiry form.

If you would rather have us build and run it, full WhatsApp automation starts from $1,499; see what drives the price and our WhatsApp AI agent service.

Frequently asked questions

Related reading

• Case studyWhatsApp AI Agent for Restaurants: Two Live n8n BuildsRead it
• ArticleEvolution API vs WhatsApp Cloud API: An Honest ComparisonRead it
• ArticleWhatsApp Chatbot Cost: What Drives the Price of an AI AgentRead it
• Articlen8n vs Zapier vs Make: Which We Pick for Client ProjectsRead it