How do you build a WhatsApp AI agent with n8n?
Create a Meta app with the WhatsApp product, add two n8n credentials, then chain a WhatsApp Trigger, a filter, an AI Agent with memory and tools, and a WhatsApp Business Cloud send node. Subscribe the app to your WhatsApp Business account, test with real messages, and publish.
This guide walks through that build node by node, using only n8n's official WhatsApp nodes and Meta's Cloud API documentation, both read on October 30, 2026. It is the technical half of what we do on our WhatsApp automation for business service, where we also handle Meta's message fees, templates and the CRM connection. If you would rather have the agent built and maintained for you, that page explains how.
We cover what you need first, the credentials, the workflow, the instructions and tools, the 24-hour rule, testing, and a table of the errors that stop most first builds. Exact menu names in Meta's dashboard change often, so we name the pages the docs name and you may find a button one click away from where we say.
What do you need before you start?
A Meta developer account, a Meta business portfolio, a Meta app with the WhatsApp product added, a phone number for WhatsApp, an n8n instance reachable on a public HTTPS URL, and an API key for the language model the agent will use.
n8n's WhatsApp Business Cloud credentials page lists the Meta side. We add the n8n and model side from our own builds.
| Item | Where it comes from | Note |
|---|---|---|
| Meta developer account | Meta for Developers, verified with a phone number | Use a business owner's login, not a freelancer's |
| Meta business portfolio | Meta Business settings (once called Business Manager) | WhatsApp messaging requires one; it should be in the business's name |
| Meta business app with WhatsApp | Meta App Dashboard: create app, add the WhatsApp product, pick the portfolio | Set Privacy Policy and Terms of Service URLs, then switch the app to Live mode |
| Phone number | Added in the app's WhatsApp setup | Meta provides a test number for trying things out |
| n8n instance | n8n Cloud or self-hosted | Meta must reach the webhook URL over the public internet |
| Language model key | Your model provider (OpenAI, Anthropic, Google and others) | Pick a provider whose business terms keep your data out of training |
Create every account in the business's name. The number's quality rating and messaging limit belong to the portfolio that holds it, so an agency-owned portfolio is hard to leave later. Our page on who owns the automations and data covers the general rule.
How do you connect WhatsApp to n8n?
n8n uses two WhatsApp credentials. The send node takes an access token and your WhatsApp Business Account ID. The WhatsApp Trigger takes an OAuth2 credential made from your Meta app's App ID and App Secret. Use a system user token, because the dashboard token expires within hours.
Credential 1: WhatsApp API (for the send node)
n8n's docs say to open your app in the Meta App Dashboard, go to WhatsApp, then API Setup, select Generate access token, and copy the token and the WhatsApp Business Account ID into n8n. That token is a user access token. Meta's access tokens page says these "expire quickly, so you have to keep generating a new one every few hours", and its get-started guide says the temporary token "is not suitable for development purposes".
For a live agent, create a system user token instead. Meta's steps: in Business settings, open System Users, add one with the Admin or Employee role, assign your app to it with the Manage app permission, then select Generate token, choose your app and an expiration, and grant the permissions. Meta lists three for the system token: whatsapp_business_messaging, whatsapp_business_management and business_management. Paste that token into the n8n credential in place of the temporary one.
Credential 2: WhatsApp OAuth (for the trigger)
In the Meta App Dashboard, open App settings, then Basic. Copy the App ID into n8n as the Client ID and the App Secret as the Client Secret. Keep the App Secret out of shared screenshots and documents.
What does the n8n workflow look like, node by node?
Six nodes do the core job: WhatsApp Trigger on Messages, an If node that drops status updates, an AI Agent with a chat model, Simple Memory keyed on the sender's number, one or more tools, and a WhatsApp Business Cloud node that sends the reply to the same number.
The core WhatsApp AI agent workflow in n8n
| Node | Job | Key setting |
|---|---|---|
| WhatsApp Trigger | Starts the workflow when a message arrives | Trigger on the Messages update; the node also offers template status, quality and account updates |
| If (or Switch) | Lets real customer messages through | Continue only when the item has a messages array; route text, audio and other types separately |
| WhatsApp Business Cloud, Media Download (optional) | Fetches a voice note or image the customer sent | Pass the file to a transcription or vision step before the agent |
| AI Agent | Reads the message, decides, calls tools, writes the reply | Prompt set to the message text; system message with your rules |
| Chat model (sub-node) | The language model the agent uses | Any model with reliable tool calling |
| Simple Memory (sub-node) | Remembers the last few turns of this chat | Session Key set to the sender's number |
| Tools (sub-nodes) | Calendar, CRM lookup, knowledge base, hand-off | At least one tool is required |
| WhatsApp Business Cloud, Send | Sends the reply | Your Phone Number ID as sender; the customer's number as recipient |
Why the If node matters
Meta's messages webhook reference says status notifications for your own outgoing messages arrive in a statuses array, with separate notices for sent, delivered and read. Without a filter, each reply your agent sends can start the workflow up to three more times. Customer messages arrive in a messages array instead: the sender's number is in messages[0].from, the message type in messages[0].type and the text in messages[0].text.body. Open the trigger's output panel in n8n to see where these fields sit in your item, then point the If node, the agent prompt and the send node at them.
Memory and the session key
n8n's Simple Memory node stores the conversation under a Session Key you set, and its Context Window Length sets how many earlier turns the agent sees. Use the sender's number as the key so each customer gets their own history. The docs warn: "Don't use this node if running n8n in queue mode", because calls can land on different workers. On a queue-mode instance, use a database-backed memory node instead.
How should you write the agent's instructions and tools?
Write the system message about your business only: what you sell, prices, hours, booking rules, and when to hand off. Give each tool a name that says its job and a description that starts with when to use it. Keep off-topic questions out.
The AI Agent node works as a tools agent and "You must connect at least one tool". A WhatsApp agent for a service business usually needs four:
- check_availability and book_appointment: your calendar or booking system, through its n8n node or an HTTP Request tool.
- find_customer: a CRM lookup by phone number, so the agent knows if this is an existing customer.
- search_knowledge: your services, prices and policies, from a document store or a vector store.
- hand_off_to_person: creates a task or alert for a team member and tells the customer someone will reply.
Scope matters for two reasons beyond answer quality. Meta's terms bar AI that is offered as the "primary" functionality on WhatsApp, and a business agent stays clearly allowed when it only handles that business's customers; our page on whether WhatsApp is banning AI chatbots explains the rule. And WhatsApp's Business Messaging Policy says automation must come with "prompt, clear, and direct escalation paths", which is what the hand-off tool is for.
The WhatsApp Business Cloud node also has a Send and Wait for Response operation. n8n's node docs say it can act as a human review step, where "the AI Agent will pause and request human approval" before running a tool, for example before it cancels a booking. If the agent answers without calling its tools, our fix list for an n8n AI Agent not calling tools goes through the causes.
How does the 24-hour window affect an n8n WhatsApp agent?
The agent can reply freely only within 24 hours of the customer's last message. After that, n8n must send an approved template with the Send Template operation. Free-form replies are service messages: 1,000 a month per number are free, then Meta charges by country.
Meta's Business Messaging Policy puts it plainly: "You may use automation when responding during the 24-hour window." A reply sent by the agent seconds after the customer writes is always inside the window. The window matters for follow-ups: a reminder tomorrow, a "did you still want that slot?" nudge, or a hand-off reply from a person who answers the next day. Build those as template sends, and store the time of the customer's last message on the contact so the workflow can choose.
On cost, Meta's pricing page sets the service message rate by the customer's country code. On the USD sheet effective October 1, 2026, it is $0.0034 per message in the US and Canada and $0.022 in the UK. Our WhatsApp rates by country research covers the other markets, and the money page works out a full month for a typical business. The model provider bills separately for each reply the agent writes.
How do you test the agent and go live?
Test on the test webhook URL with a few real phones, then publish the workflow so the production URL is registered. Check that your app is subscribed to the WhatsApp Business account, send a real message, and confirm an execution appears. Then watch the first days closely.
n8n's WhatsApp Trigger docs flag two traps that cause most "it worked yesterday" reports:
- One webhook per app. "WhatsApp only allows you to register a single webhook per app." Switching between test and production overwrites the registered URL, so only one of them receives events. n8n's workaround is to unpublish, test on the test URL, then publish again, which "Halts production traffic" while unpublished. For a live agent, a second Meta app and number used only for testing avoids the problem. The general version of this problem is in our FAQ on n8n test versus production webhook URLs.
- App not subscribed to the WABA. Meta only sends webhooks to apps subscribed to the WhatsApp Business account. Publishing registers the URL but does not subscribe the app, and nothing shows as a failed execution. A passing test event from the App Dashboard does not prove the subscription. Check with a GET request to the account's subscribed_apps endpoint and POST to it if your app is missing. Do not send a DELETE to clear an error, because that unsubscribes the app.
Our test script before launch covers a booking, a price question, an off-topic question, a voice note, a request for a person, an opt-out, and a reply sent after the 24-hour window, each checked in the n8n execution log.
What goes wrong with n8n WhatsApp agents, and how do you fix it?
The common faults are silent: no executions because the app is not subscribed, a token that expired after a few hours, replies that loop on status updates, memory that mixes customers, and template-only errors after the 24-hour window. Each has a quick check.
Where to look when the agent fails
| Symptom | Likely cause | Fix |
|---|---|---|
| No executions at all when customers write | App not subscribed to the WhatsApp Business account | GET subscribed_apps; POST to add your app |
| Works in test, silent in production (or the reverse) | One webhook per app; the other URL overwrote it | Publish once; test on a second app and number |
| Sending stops after a few hours | Temporary token from API Setup expired | Create a system user token and update the credential |
| "Error fetching options" in the WhatsApp Business Cloud node | Check the credential first: an expired token or a wrong Business Account ID | Regenerate the token and recheck the ID in API Setup |
| The workflow runs three extra times per reply | Sent, delivered and read statuses trigger it | If node: continue only when a messages array exists |
| The agent mixes up two customers' details | Session Key not set to the sender's number, or Simple Memory in queue mode | Key on messages[0].from; use database memory in queue mode |
| Follow-up sends fail the next day | Free-form message outside the 24-hour window | Use Send Template with an approved template |
| The agent answers without booking | Vague tool names or descriptions | Name tools by job; say when to use each |
Should you build the agent in n8n or in GoHighLevel?
Use n8n when the agent must call several outside systems, such as a booking platform, an ERP or a custom database. Use GoHighLevel's Conversation AI when your contacts, calendar and pipeline already live in HighLevel. Many of our builds use both.
n8n or GoHighLevel for the agent
HighLevel runs WhatsApp inside its Conversations inbox and has enabled Conversation AI on the WhatsApp channel, so a business already on HighLevel can answer and book without a separate workflow tool. n8n gives more control over tools, models and data, at the cost of hosting and maintaining the workflow yourself. A common pattern is HighLevel for the inbox and pipeline, with n8n handling the calls to outside systems. Our n8n automation and GoHighLevel automation pages describe each side, and the AI chat agent service covers running the same agent on WhatsApp, website chat and Instagram.
More questions about WhatsApp AI agents in n8n
Is the n8n WhatsApp integration free?
The WhatsApp nodes come with n8n, so there is no extra charge for the nodes themselves. You still pay for n8n hosting or an n8n Cloud plan, Meta's per-message fees on the WhatsApp Business Platform, and your language model provider's usage fees. Each phone number gets 1,000 free service replies a month before Meta charges for them.
Can I connect my existing WhatsApp Business app number to n8n?
Yes, through Meta's coexistence onboarding, which links a WhatsApp Business app number to the Cloud API so messages are mirrored between the app and the API. Meta's coexistence documentation lists limits, including a fixed 20 messages per second and no group chat sync. Otherwise you register a number that is not on the app.
Do I need a verified business to build a WhatsApp agent in n8n?
Not to build and test. You can start with Meta's test number. To message customers at scale you need a business portfolio, and Meta's messaging limits start new portfolios at 250 customers a day outside the service window; verifying your business is one path to 2,000, subject to Meta's quality review. Replies inside the 24-hour window do not count toward that limit.
Can an n8n WhatsApp agent reply to voice notes?
Yes. Route audio messages to the WhatsApp Business Cloud node's Media Download operation, send the file to a speech-to-text step, and pass the transcript to the AI Agent as the prompt. The reply can go back as text. Images work the same way with a model that reads images.
Which AI model should you use for a WhatsApp agent in n8n?
Choose a model that calls tools reliably and keeps replies short, then test it on your own scripts. Most major providers offer one that works in n8n's AI Agent node. Cost per reply and the provider's data terms matter as much as quality, since Meta's terms bar using WhatsApp data to train general models.
Can I use an n8n template for a WhatsApp AI agent?
Yes. n8n's WhatsApp node pages link to community workflow templates, which are a useful starting point. Before going live, replace the sample prompt with your own business rules, add the status filter and session key described above, check every credential, and add a hand-off path, because templates usually leave those parts to you.
Is it allowed to use an AI agent on WhatsApp Business?
Yes, for your own business. Meta's terms bar AI providers from offering general-purpose assistants as the product, outside a few markets such as the EEA, Brazil and Türkiye. An agent that answers your own customers, books appointments and hands chats to your team is allowed, provided you keep chat data out of model training.
Sources and further reading
- n8n docs, WhatsApp Trigger node, checked October 30, 2026.
- n8n docs, WhatsApp Business Cloud node, checked October 30, 2026.
- n8n docs, WhatsApp Business Cloud credentials, checked October 30, 2026.
- n8n docs, AI Agent node and Simple Memory node, checked October 30, 2026.
- Meta for Developers, Access tokens and Cloud API get started, checked October 30, 2026.
- Meta for Developers, messages webhook reference, checked October 30, 2026.
- Meta for Developers, Messaging limits and Onboarding WhatsApp Business app users (coexistence), checked October 30, 2026.
- Meta for Developers, Pricing on the WhatsApp Business Platform, USD list rates effective October 1, 2026, checked October 30, 2026.
- WhatsApp, WhatsApp Business Messaging Policy, last updated September 23, 2026, checked October 30, 2026.
