n8n AI Agent WhatsApp Channel Tutorial: Build a WhatsApp Chatbot Powered by an n8n AI Agent

Introduction

A WhatsApp chatbot that understands customers instead of matching keywords is a real business asset. This tutorial builds one: a WhatsApp Business number connected through Meta’s Cloud API, wired into an n8n workflow where a WhatsApp Trigger feeds each incoming message into an n8n AI Agent, which thinks, calls a tool, remembers the conversation, and replies through the WhatsApp send node. It is for n8n users who know the editor and want a production-grade messaging channel for an agent. You will complete the real Meta dashboard setup, verify the webhook handshake, and learn the two rules that break most first attempts: the 24-hour customer service window and the single-webhook-per-app limit.

Quick answer

Connect a WhatsApp Business number via Meta’s Cloud API, register n8n’s WhatsApp Trigger webhook, route incoming text to an AI Agent node with a chat model and memory, then send the answer back with the WhatsApp send node.

The evidence: why this stack, and what it costs

WhatsApp is the largest messaging channel on the planet. Meta states on its own about page, as of Oct 2026: “More than 3 billion people in over 180 countries use WhatsApp to stay in touch with friends and family, anytime and anywhere.” That is the audience argument for WhatsApp over another web chat widget: your customers already have the app installed.

The tooling argument comes from n8n’s AI Agent node documentation, which describes the node this way: “The AI Agent node lets you build an AI agent in n8n. Connect a chat model and one or more tools, and the agent decides which tools to call to complete a task.” The same page notes you must connect at least one tool sub-node, so the pattern below (trigger, agent, model, memory, one HTTP tool) follows the documented design.

Pricing is the part people get wrong, so pin it to the source. Meta’s WhatsApp Business Platform pricing documentation publishes per-market rates across four message categories: marketing, utility, authentication, and service. API access itself is free; you pay per delivered message, and replies to customer-initiated chats are the cheapest category. Check the live rate card for your recipients’ countries before budgeting.

One more documented limit shapes the architecture. n8n’s WhatsApp Trigger node documentation states: “WhatsApp only allows you to register a single webhook per app. This means that every time you switch from using the testing URL to the production URL (and vice versa), WhatsApp overwrites the registered webhook URL.” Keep that sentence in mind while testing. It is the number-one reason a workflow that worked five minutes ago suddenly goes silent.

Prerequisites

• An n8n instance reachable over HTTPS. n8n Cloud works out of the box. Self-hosted n8n (2.x) must expose a public HTTPS webhook URL, for example behind a reverse proxy with a valid certificate, because Meta only calls back to HTTPS endpoints.
• A Meta developer account and a Meta Business portfolio at business.facebook.com.
• A phone number that is NOT registered with WhatsApp or the WhatsApp Business app. A fresh prepaid SIM or virtual number both work.
• A second phone with WhatsApp installed for testing inbound messages. You cannot test by messaging the business number from itself.
• An API key for a chat model (examples below use an OpenAI chat model; any n8n-supported model works).
• Beginner-to-intermediate n8n skills: adding nodes, writing simple expressions, creating credentials.

Step-by-step guide

Step 1: Create the Meta app and enable the WhatsApp product

Sign in at developers.facebook.com and create an app. Choose the Business use case and attach the app to your Meta Business portfolio. In the app dashboard, find the WhatsApp product card and click Set Up. Meta provisions a sandbox immediately: a test phone number, a temporary access token, a Phone Number ID, and a WhatsApp Business Account ID, all visible on the API Setup page. The Cloud API get-started guide covers this sequence with screenshots.

To go live, register your own number under API Setup instead of the test number. Meta verifies it with an SMS or voice-call OTP, and the number must not be registered in any WhatsApp app.

Step 2: Create the two n8n credentials

The integration needs two different credentials, and mixing them up is a classic mistake:

1. OAuth credential for the trigger. Create a WhatsApp Business Cloud credential with the OAuth method. It asks for a Client ID and a Client Secret: paste your Meta App ID as the Client ID and your App Secret as the Client Secret (both under App Settings, then Basic). Save and test.
2. API key credential for sending. Create a second WhatsApp credential with the API key method: the access token from the Meta API Setup page plus your WhatsApp Business Account ID. The temporary token works for testing; later, generate a permanent system-user token with the whatsapp_business_messaging permission.

Step 3: Register the webhook in the Meta dashboard

In the Meta developer dashboard, go to WhatsApp, then Configuration. The webhook section has a Callback URL field and a Verify token field, as described in Meta’s webhooks documentation.

1. In n8n, add a WhatsApp Trigger node and set its event to Messages (the trigger documentation also lists account, template, and phone-number events). Attach the OAuth credential. n8n shows the webhook URL for this trigger.
2. Paste that URL into the dashboard’s Callback URL field.
3. Invent a verify token string, for example toolpilot-wa-verify-2026, enter it in the Verify token field, and paste the same string into the n8n trigger node’s verify token field. Meta only accepts the callback if the strings match exactly.
4. Click Verify and Save. Success means Meta reached your n8n instance over HTTPS and the token matched.
5. Subscribe the webhook to the messages field. Without this subscription, Meta never delivers chat events.

n8n can also register the webhook automatically when you execute the workflow.

Step 4: Inspect a real inbound payload

Send a WhatsApp message to the business number from your test phone and open the last execution. The message sits at messages[0] in the trigger output. The two fields you will reuse are the sender, {{ $json.messages[0].from }}, and the text, {{ $json.messages[0].text.body }}.

Step 5: Add the AI Agent node with model, memory, and a tool

Add an AI Agent node after the trigger, with three sub-nodes:

1. Chat Model. Add your model of choice and attach its credential.
2. Simple Memory. Set the session key to the sender’s phone, ={{ $json.messages[0].from }}, so each WhatsApp user keeps their own history. The n8n chatbot memory tutorial covers the memory options in depth.
3. One tool. The docs require at least one tool sub-node. A weather lookup is ideal because the API needs no key: add an HTTP Request sub-node as a tool, method GET, URL https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current=temperature_2m, with a description like “Returns the current temperature in Berlin; use when the user asks about weather.” The agent reads the description to decide when to call it.

Set the agent prompt to Define below with the expression ={{ $json.messages[0].text.body }}. Add a system message: “You are a helpful support assistant replying on WhatsApp. Keep answers under 300 characters, plain text only, no markdown formatting.” WhatsApp renders plain text best. If the node is new to you, the n8n AI Agent tutorial walks through the same settings.

Step 6: Reply with the WhatsApp send node

Add a WhatsApp Business Cloud node after the agent, operation Message, then Send. The node documentation lists the other operations too: Send and Wait for Response, Send Template, and media upload, download, and delete. Configure:

• Credential: the API key credential from Step 2.
• Sender (phone number ID): the Phone Number ID from the Meta API Setup page.
• Recipient: ={{ $('WhatsApp Trigger').item.json.messages[0].from }}
• Text Body: ={{ $json.output }} (the agent’s answer).

The chain is now: WhatsApp Trigger, AI Agent (model, memory, weather tool), WhatsApp send node.

Step 7: Filter to real text messages

Meta also delivers status events (sent, delivered, read) to the same webhook. Add an IF node after the trigger with the condition ={{ $json.messages[0].type }} equals text, and route only the true branch into the agent. Without this filter, delivery receipts trigger agent runs that burn model tokens answering nothing.

Step 8: Test the loop and the memory

Activate the workflow and send “what is the weather like?” from the test phone. The agent should call the weather tool and reply with the temperature in plain text.

Step 9: Respect the 24-hour customer service window

When a customer messages your business, a 24-hour customer service window opens, and each customer reply resets the clock. Inside the window you may send free-form text, which is what the Send operation does. Outside the window the API rejects free-form messages; you must use an approved template via the Send Template operation. Design around this: proactive follow-ups need templates created and approved in the Meta dashboard first. The agent answers; it does not do cold outreach.

Step 10: Go live checklist

• Replace the temporary access token with a permanent system-user token carrying the whatsapp_business_messaging permission.
• Complete Meta business verification and register your real number with OTP.
• Confirm n8n serves webhooks over public HTTPS. For self-hosted setups, set the WEBHOOK_URL environment variable to the public URL. The self-hosted webhook fix guide covers reverse-proxy pitfalls.
• Publish the production workflow and test against the production URL, since WhatsApp keeps only one webhook per app.

Troubleshooting

Webhook verification fails in the Meta dashboard

Symptom: Verify and Save reports that the callback URL or verify token could not be verified.

Cause: Usually one of three things: the token in the dashboard does not exactly match the one in the n8n trigger (extra spaces count), the callback URL is not reachable from the public internet, or it is plain HTTP. Meta only calls HTTPS endpoints.

Fix: Re-type the token on both sides instead of copying it, since invisible whitespace is the usual culprit. Then fetch the n8n webhook URL from a public network and confirm it answers over HTTPS. Self-hosted instances behind NAT or a misconfigured proxy are the most common root cause; check that WEBHOOK_URL matches the public address.

The trigger fires in testing but never in production

Symptom: The workflow works on Test workflow, but activating it produces no executions for real messages.

Cause: n8n’s docs explain it: “WhatsApp only allows you to register a single webhook per app. This means that every time you switch from using the testing URL to the production URL (and vice versa), WhatsApp overwrites the registered webhook URL.” Your last test registered the test URL, so production events go nowhere.

Fix: Publish the workflow, then run one production execution so n8n re-registers the production webhook. Confirm in the dashboard’s Configuration panel that the callback URL is the production one.

Replies fail outside the 24-hour window

Symptom: The send node throws an API error (Meta reports error 131047, the re-engagement message error) when answering a customer who last wrote over a day ago.

Cause: The 24-hour customer service window closed. Meta rejects free-form text once it lapses.

Fix: Send an approved message template with the Send Template operation, and wait for the customer to reply, which reopens the window. Build the template library in the Meta dashboard before you need it; review takes time.

The bot answers delivery receipts and wastes tokens

Symptom: The agent executes on events with no user text, producing empty or confused replies.

Cause: Meta delivers status events (sent, delivered, read) to the same webhook, and the workflow has no filter.

Fix: Add the IF node from Step 7 so only messages[0].type equal to text reaches the agent.

The temporary access token stops working

Symptom: Sending worked yesterday; today every send fails with an authentication error, while the trigger still receives messages.

Cause: The temporary token from the API Setup page expired. The trigger uses the separate OAuth credential, which is why inbound kept working.

Fix: Create a system user in Business Settings, grant the WhatsApp permissions including whatsapp_business_messaging, generate a permanent token, and swap it into the API key credential in n8n.

The agent never calls the weather tool

Symptom: The bot guesses answers from its own knowledge instead of calling the HTTP tool.

Cause: The tool description is too vague for the agent to match it to the question.

Fix: Rewrite the description as a when-to-use instruction naming the trigger phrases (“use when the user asks about weather, temperature, or forecast”). The AI Agent tool-calling fix guide documents this failure pattern with more examples.

FAQ

Can I use my existing personal WhatsApp number for the n8n chatbot?

No. Meta requires a phone number that is not registered with WhatsApp or the WhatsApp Business app. Use a new SIM or virtual number, or migrate a number by deleting it from the WhatsApp apps first.

Does the WhatsApp Cloud API cost money to use with n8n?

API access is free. You pay Meta per delivered message in four categories (marketing, utility, authentication, service). Replies to customer-initiated chats are the cheapest. Confirm per-market rates on Meta’s pricing page.

Do I need Meta business verification to build this tutorial’s bot?

Not for the sandbox stage; the test number works without it. You must complete business verification before going live with your own number and messaging real customers.

Why doesn’t my workflow trigger when I message the business number?

Usual causes: you messaged from the same phone (WhatsApp does not deliver that as an inbound event), the webhook is not subscribed to the messages field, or the test URL is registered while you expect production traffic, since WhatsApp allows only one webhook per app.

How does the agent remember what a customer said earlier?

Attach a Simple Memory sub-node to the AI Agent node and set its session key to the sender’s phone number from the trigger payload, so each number gets its own conversation history.

Can the bot message customers who never contacted me first?

Only with Meta-approved message templates. Outside the 24-hour customer service window, free-form text is rejected; send a template with the Send Template operation.

Conclusion

You now have a WhatsApp channel wired to a real AI agent: Meta’s Cloud API delivers messages to n8n, the WhatsApp Trigger feeds them to an AI Agent with memory and a tool, and the send node carries answers back inside the 24-hour service window. The two fixes that save the most debugging time are respecting the single-webhook-per-app rule and replacing the temporary token before launch. Next, give the agent real business knowledge: the n8n AI agent builder tutorial shows how to expand a single agent into a structured assistant, and the Meta WhatsApp MCP server setup connects the same WhatsApp account to Claude-based tooling for a different automation angle.

Frequently asked questions