On this page · 10 sections
A WhatsApp AI agent in n8n is a workflow that receives each incoming WhatsApp message, lets an AI model decide what to reply and which tools to use, and sends the answer back through the WhatsApp Business Cloud API. The core chain is WhatsApp Trigger → AI Agent (chat model + memory + tools) → WhatsApp Business Cloud “Send”, with your CRM and a human handoff connected as tools. You need a Meta business app with WhatsApp, an n8n instance on a public URL, and clear rules for what the agent may and may not do.
This guide builds a lead-qualification agent: it greets new leads, asks a few qualifying questions, writes the answers to your CRM, and hands the conversation to a person at the right moment.
What the agent should (and shouldn’t) do
Most failed WhatsApp bots fail because they try to do everything. A lead-qualification agent has a narrow job:
- Do: reply within seconds, answer a short list of known questions, collect qualifying details, create or update the CRM contact, and hand over to sales with a summary.
- Don’t: quote custom prices, promise delivery dates, negotiate, or keep chatting when the lead asks for a person.
WhatsApp’s own rules point the same way. As of October 2026, the WhatsApp Business Messaging Policy says you may only message people who gave you their number and opted in, free-form replies are only allowed inside the 24-hour customer service window that opens with each user message, and automation in that window must come with prompt, clear escalation paths, such as a transfer to a human agent. Build the handoff in from day one, not as an afterthought.
The architecture
- WhatsApp Trigger (event: Messages) receives the incoming message.
- Filter keeps real messages and drops delivery/read status updates.
- Edit Fields (Set) extracts the phone number, profile name and message text.
- Handoff check: if a person has taken over this conversation, stop here.
- AI Agent with a chat model, memory keyed on the phone number, and tools: CRM lookup/update and “hand off to a human”.
- WhatsApp Business Cloud → Send sends the agent’s reply.
What you need before you build
According to n8n’s WhatsApp credentials guide, you need three Meta assets: a Meta developer account, a Meta business portfolio (formerly Business Manager), and a Meta business app with WhatsApp added. Then create two credentials in n8n:
- WhatsApp API (API key) for the WhatsApp Business Cloud node: an access token and your WhatsApp Business Account ID, both from WhatsApp > API Setup in your Meta app.
- WhatsApp OAuth2 for the WhatsApp Trigger: your Meta app’s App ID and App Secret, from App settings > Basic.
Two more decisions come before any nodes:
- Which number and which inbox. If your sales team already works WhatsApp from HubSpot or another CRM inbox, decide how the bot and that inbox share the number. That choice is covered in which WhatsApp–HubSpot connection to use.
- Where the “truth” lives. The CRM, not the chat memory, should hold the lead’s qualification data. Memory is for the conversation. The CRM is the record.
One gotcha to know up front: WhatsApp allows only one webhook per app. n8n’s WhatsApp Trigger documentation explains that switching between the test and production URLs overwrites the registered webhook, so a published workflow and a test run can’t both receive messages. To test, unpublish the workflow first, then publish again when you’re done.
Before automating replies, it’s worth knowing where leads drop today. If you’d like a second pair of eyes, I can see where your WhatsApp lead flow leaks as part of a free audit.
Build it step by step
1. WhatsApp Trigger and the message filter
Add a WhatsApp Trigger node with your OAuth2 credential and subscribe to the Messages event. Send a message to your business number and look at the output. Besides incoming messages, this event also carries status updates (sent, delivered, read) for messages you send. If you don’t filter them out, your agent will try to “reply” to its own delivery receipts.
Add a Filter node that only passes items containing a messages array. Decide what to do with non-text messages (voice notes, images, locations). The simple version sends a polite “please type your question” reply, or routes them straight to a human.
2. Normalise the message
Use an Edit Fields (Set) node to pull out three values with clear names: phone (the sender’s WhatsApp ID), name (their profile name, if present) and text (the message body). Everything after this node reads these names, which keeps the agent prompt and tools simple.
3. The AI Agent node: model, memory, system message
Add an AI Agent node. Per n8n’s AI Agent documentation, it needs a chat model and at least one tool, and since n8n 1.82.0 every AI Agent works as a tools agent. Set the prompt source to your text field.
- Chat model: connect the provider you already use. Pick one that handles tool calling reliably and writes well in your leads’ languages, then test it on real conversations.
- Memory: connect a memory sub-node and set the session key yourself to the sender’s
phone. The default session key expects n8n’s chat trigger, which is behind the common “no session ID found” error. Keying on the phone number gives each lead their own conversation history. For production, use a database-backed memory rather than one held in the n8n process. - System message: this is where the agent’s job lives. Keep it specific.
A system message skeleton you can adapt:
You are the first-response assistant for [Company] on WhatsApp.
Goal: understand what the lead needs and collect: service needed,
company or website, timeline, and budget range.
Rules:
- Reply in the language the lead writes in. Keep replies under 60 words.
- Ask one question at a time. Never ask for something already in the CRM.
- Use the crm_lookup tool before your first reply, and crm_update
whenever you learn a new detail.
- Never quote prices, discounts or delivery dates.
- If the lead asks for a person, is unhappy, or all details are
collected, call handoff_to_human with a 2-line summary, then tell
the lead a team member will reply here.
- If you don't know an answer, say so and offer the handoff.4. Give it tools: CRM and handoff
Tools are what make this an agent rather than a chatbot. Attach them to the AI Agent node:
- crm_lookup: your CRM’s n8n node (or an HTTP Request tool) that searches contacts by phone number and returns known fields.
- crm_update: creates the contact if missing, or updates the qualification properties. Give the agent only the properties it needs, not full write access to every object.
- handoff_to_human: a Call n8n Workflow tool that runs a small sub-workflow. It marks the conversation as handed off (a CRM property or a row in a table), alerts the sales owner with the summary, and assigns the contact.
Write each tool’s description as an instruction: when to use it, what it needs, what it returns. Vague tool descriptions are the usual reason an agent “isn’t using tools”. If leads also arrive from website forms, the same sub-workflows can serve both channels. See how webhook triggers in n8n bring form leads into the same flow.
5. Send the reply
Add a WhatsApp Business Cloud node with the API key credential: resource Message, operation Send, recipient = phone, text = the agent’s output. Free-form Send only works inside the 24-hour window. For any follow-up after that, such as a reminder the next day, use Send Template with a template Meta has approved. The node’s full list of operations is in n8n’s WhatsApp Business Cloud documentation.
6. Human handoff and approvals
Back at the start of the workflow, after the Set node, add an If node that checks the handoff flag for this phone number. If a human owns the conversation, the workflow stops and the agent stays quiet. Clear the flag when sales closes the conversation or after an agreed period.
For riskier actions, n8n supports human-in-the-loop review of AI tool calls, and the WhatsApp Business Cloud node can be the approval channel. The agent pauses and asks a team member to approve before the tool runs. Use it for anything you wouldn’t want a model doing alone, such as moving a deal stage or booking a call on someone’s calendar.
This is the kind of system I build under AI-powered workflows: WhatsApp, n8n and the CRM working as one flow, with a person always one step away. WhatsApp is a required field on my own audit form, so I treat it as a main lead channel, not an add-on.
Designing the qualification questions
Ask as little as you can and store every answer as a CRM property, not just in the chat. A starting set for a B2B service business:
| Field | Why it matters | Example question | Store as |
|---|---|---|---|
| Service needed | Routes to the right owner | “What can we help you with?” | Dropdown property |
| Company or website | Lets sales research before replying | “What’s your company website?” | Text / company association |
| Timeline | Separates urgent from exploring | “When are you hoping to start?” | Dropdown (this month / this quarter / later) |
| Budget range | Filters poor fits early | “Do you have a budget range in mind?” | Dropdown of ranges |
| Handoff summary | Sales starts with context | (written by the agent) | Note on the contact |
Use dropdown-style properties where you can. The agent can map free text to a fixed option, and your reports stay clean.
Test and go live
- Unpublish the workflow and test with the test URL (remember the one-webhook rule).
- Run at least ten scripted conversations: an ideal lead, a vague one, someone who asks for a person straight away, a voice note, a message in each language you support, and a request for a price.
- Check the CRM after each one: correct contact, correct properties, no duplicates.
- Publish, then read real transcripts daily for the first two weeks and tighten the system message.
- Watch the three running costs: your n8n hosting or plan, your model provider’s usage, and Meta’s WhatsApp charges. Check each provider’s current pricing page.
Common problems and fixes
| Problem | Likely cause | Fix |
|---|---|---|
| “No session ID found” | Memory expects the chat trigger’s session | Define the session key as the sender’s phone number |
| Agent ignores tools | Vague tool names or descriptions; prompt doesn’t require them | Describe when to use each tool; tell the agent to look up the CRM first |
| Bot replies twice or to nothing | Status updates not filtered | Only pass items that contain a message |
| Works in test, silent when published | Test URL overwrote the app’s single webhook | Re-publish the workflow so the production URL is registered again |
| Follow-up message fails next day | Outside the 24-hour window | Use Send Template with an approved template |
| Bot talks over the sales rep | No handoff check | Check the handoff flag before the AI Agent node |
When not to build this
If you get a handful of WhatsApp leads a day and someone answers within minutes, a shared inbox with saved replies may serve you better than an agent. The agent pays off when replies are slow, leads arrive out of hours, or sales spends its time asking the same four questions. Fix routing and response times first. Then automate.
FAQ
Can n8n be used to build AI agents?
Yes. n8n’s AI Agent node connects a chat model, optional memory and one or more tools, and the agent decides which tools to call to finish a task. WhatsApp is one of many channels you can put in front of it.
Is an n8n WhatsApp AI agent free?
The AI Agent node is part of n8n, but the system has running costs: hosting n8n yourself or paying for n8n Cloud, your AI model provider’s usage fees, and Meta’s charges for WhatsApp messages. Check each provider’s current pricing.
Can the agent message a lead after 24 hours?
Only with an approved message template. Free-form replies are allowed inside the 24-hour customer service window, which resets each time the lead messages you. Outside it, use the node’s Send Template operation.
Which AI model is best for lead qualification?
The prompt, tools and handoff rules matter more than the model. Choose one that calls tools reliably and writes naturally in your leads’ languages, and judge it on your own test conversations.
Where this fits
An agent only helps if the rest of the lead flow works: tracking, CRM routing and a fast human follow-up. Use the audit checklist to check your lead flow end to end. The same agent pattern also works beyond WhatsApp, for example letting agents act on your WordPress site with tightly scoped permissions.
More in AI Workflows
AI Workflows How to Connect an AI Agent to WordPress Safely (MCP, REST API and Permissions)
Connect Claude, Cursor or any MCP agent to WordPress with the Abilities API, MCP Adapter and Application Passwords, without handing over admin.
Automation & Integrations Why Is Zapier So Expensive? How to Cut Your Bill (and When to Move to n8n)
Zapier bills per task, and every action step counts. Find the Zaps eating your plan, cut them, and know when n8n or custom code is cheaper.