Saltar al contenido principal
    Skip to main content

    How to build a WhatsApp AI agent with n8n and the official Cloud API

    In n8n you need the WhatsApp Trigger, an AI Agent node with a model, memory and tools, and the send node. Steps, common failures and where to host it.

    By Filip Balik, co-founder · Updated on 24 October 2026

    To build a WhatsApp AI agent with n8n you need a Meta app with a number on the Cloud API and four n8n pieces: the WhatsApp Trigger node, which receives messages; the AI Agent node, with a model, memory and tools; the WhatsApp Business Cloud node, which replies; and a table where you log every conversation. That gives you an agent that answers inside the 24-hour window and hands over to a person when it doesn't know.

    This guide is the hands-on n8n part. The general explanation (scope, number, templates, testing) is in how to build a WhatsApp AI agent, and if you are new to the tool, start with what n8n is.

    What pieces do you need?

    Piece Node or service What it does
    Meta app and number Meta developer dashboard The agent's identity and its access to the Cloud API
    Input WhatsApp Trigger, Messages event Starts the workflow with each message
    Brain AI Agent with a chat model node Understands the message and decides what to do
    Memory Simple Memory or Postgres Chat Memory Remembers the conversation
    Tools Call n8n Workflow Tool, HTTP Request, Google Calendar and others Looks things up and acts in your systems
    Output WhatsApp Business Cloud, Send operation Sends the reply
    Log Data Table Stores each message, blocks duplicates and records who is handling the chat
    Errors Error Trigger Alerts you when the workflow fails

    The AI Agent node won't run without two things: a connected model and at least one tool. Its documentation lists the chat model nodes for OpenAI, Anthropic, Mistral, Groq and Microsoft Foundry as supported.

    How do you connect n8n to your WhatsApp account?

    You need a Meta developer account, a business portfolio and an app with the WhatsApp product. In the app's basic settings, fill in the privacy policy URL and the terms of service URL, and switch the app mode to Live, as the n8n credentials guide explains.

    n8n uses two different credentials, and creating only one is a common mistake:

    Node Credential type What it asks for Where you find it
    WhatsApp Trigger OAuth2 Client ID and Client Secret App ID and App Secret, under App settings > Basic
    WhatsApp Business Cloud API key Access Token and Business Account ID WhatsApp > API Setup

    The token from the API Setup button is fine to get started, but Meta warns that it expires quickly. For production, create a system user in your business settings and generate its token with three permissions: business_management, whatsapp_business_messaging and whatsapp_business_management. Keep it in the n8n credential, never typed into a node.

    Before registering the number, decide where messages are stored. Local storage can only be turned on or off while the number is unregistered, and the regions include the EU, in Germany (code DE). Mind what it covers: content at rest stays in that region, but while it is being processed it may sit in Meta data centres in other countries for up to 60 minutes on the Cloud API.

    How do you build the workflow, step by step?

    1. Add the trigger. Add a WhatsApp Trigger with the Messages event and the OAuth2 credential.
    2. Separate messages from status updates. Through the same messages field, Meta sends both the customer's messages and the status of yours. Status updates carry a statuses array instead of messages, and each message you send can trigger up to three: sent, delivered and read. Use an If or Switch node so only items with messages reach the agent.
    3. Drop duplicates and log. Meta retries unacknowledged notifications for up to 7 days, retries can arrive twice, and there is no API to fetch old notifications. Store each message in an n8n data table, which n8n itself suggests for marking what has already run, and before replying check that its ID isn't there yet. By default, all tables in an instance share a 200 MiB limit.
    4. Check who is handling it. If the table marks that conversation as "person", the workflow stops here and the agent stays quiet.
    5. Turn voice notes into text. If the message type is audio, download it with the Media > Download operation of the WhatsApp node and run it through the Transcribe a Recording operation of the OpenAI node, which accepts files up to 25 MB.
    6. Set up the agent. In the AI Agent, set Prompt to "Define below" and point an expression at the message text, which Meta sends in text.body. The other option expects a chatInput field, the one n8n's chat trigger produces; without it you get the "No prompt specified" error, and n8n's fix is exactly to switch to "Define below". In System Message, write the agent's role, what it may do, what it must not, when it hands over and that it must introduce itself as an AI. Max Iterations, the number of passes the model makes to reach an answer, defaults to 10.
    7. Connect memory and tools. Covered in the next two sections.
    8. Reply. Use WhatsApp Business Cloud > Message > Send, to the number that wrote. Send one reply per turn: the platform allows one message every 6 seconds to the same user, and delivery order is not guaranteed.
    9. Plan for errors. Create a workflow that starts with an Error Trigger and assign it under Settings > Error workflow in the main workflow. It only fires on automatic executions, not when you test by hand.

    Which memory should you use, and what session key?

    Memory keeps the history so the agent doesn't start from scratch with every message. The two usual options:

    • Simple Memory. The easiest. But it doesn't work in queue mode in a production workflow, because n8n can't guarantee every call goes to the same worker.
    • Postgres Chat Memory. Stores the history in your Postgres database and creates the table if it doesn't exist. This is the one to pick if your n8n scales or you want to query the conversations.

    Both ask for a Session Key and a Context Window Length, the number of previous exchanges sent to the model. More history means more context and also more tokens.

    The session key is the setting people get wrong most. n8n's chat trigger provides it; with any other trigger you manage it yourself, and a fixed key is only for testing: with one, all your customers would share a single conversation.

    Use Meta's user ID, not the phone number. Since early April 2026, Meta includes a business-scoped user ID (BSUID) in the user_id field of every messages notification, and incoming messages always carry it. The phone number, on the other hand, can be missing: WhatsApp is rolling out usernames gradually in 2026, and once a customer adopts one, their number drops out of notifications except in some cases, such as having exchanged messages or calls with that number in the last 30 days. Meta warns that businesses must support the BSUID to avoid losing the ability to process those messages. Two caveats: the BSUID is different for each business portfolio, and it is regenerated if the user changes number.

    Which tools do you give the agent?

    Each tool is a node connected to the agent, with a description that tells it when to use it. For your own actions, the most useful is Call n8n Workflow Tool: the agent calls another workflow of yours ("check free slots", "open an incident") and gets its result. One detail that costs hours: in production that sub-workflow must be published. If it isn't, the agent receives the error "Workflow is not active and cannot be executed" as the tool's answer and may end up telling the customer it couldn't look the data up.

    For anything sensitive, n8n lets you require human approval before the agent uses a given tool. The workflow pauses and sends the request through the channel you choose (WhatsApp, Slack, Microsoft Teams, Gmail or Outlook, among others) with the tool name and the data it wants to use. If someone approves, it runs; if they deny it, it is cancelled and the agent is told. n8n asks you to explain in the system message which tools need approval and how to respond when one is denied.

    A practical rule: small, specific tools. An agent allowed to "check the calendar" gets far fewer things wrong than one with free access to your database.

    How do you respect the 24-hour window and templates?

    When a customer messages or calls you, a 24-hour customer service window opens, and each new message from them resets it. Inside it, the agent replies with free text. Once it closes, you can only send approved templates.

    In n8n, that comes down to three decisions:

    1. Store the time of the customer's last message in the table. That tells you whether the window is still open.
    2. Before writing on your own initiative, such as a reminder or a late reply from a staff member, check the window. If it is closed, use the Send Template operation.
    3. Match the template parameters. The "Bad request - please check your parameters" error usually appears with Send Template when the data doesn't fit the template: check each parameter's type and order.

    Costs changed recently too. Since 1 October 2026, Meta charges service messages again from the 1,001st each month per number, and utility templates sent inside the window are no longer free. Spain's rates are in WhatsApp Business API pricing in Spain, and you can estimate your bill with the WhatsApp API cost calculator.

    How do you hand the conversation over to a person?

    The WhatsApp Business Messaging Policy requires prompt, clear and direct escalation paths when you automate, such as an in-chat transfer to a person, a phone number or an email address. In n8n you build it like this, based on n8n's human fallback example, which uses a tool for when the agent doesn't know the answer or isn't confident:

    1. Create a "hand over to a person" tool with Call n8n Workflow Tool and a clear description: use it if you don't know the answer, aren't sure, or the customer asks for a person.
    2. The sub-workflow marks the conversation as "person" in the table, sends the team a summary and tells the customer what happens next.
    3. The person replies. The simplest route is a phone call or an email. If you want them to answer in the chat, send the team alert with the Send and Wait for Response operation in Free Text mode, which exists in the WhatsApp node and others such as Slack; whatever the staff member writes goes to the customer with Send, always inside the 24-hour window.
    4. Set a time limit. The Limit Wait Time option resumes the workflow after a set period. If nobody has replied, offer the customer a phone number or an email address.
    5. Give the conversation back to the agent when the case is closed, by changing the flag in the table.

    If you use Send and Wait for Response, check the Append n8n Attribution option: it decides whether the message says it was sent automatically with n8n.

    Why aren't messages reaching n8n?

    The four most common failures, according to the trigger documentation:

    1. It works in testing but not when published, or the other way round. WhatsApp allows only one webhook per app, so the test URL and the production URL overwrite each other. To test a published workflow, unpublish it, test, and publish it again. Meanwhile it serves nobody.
    2. The app isn't subscribed to your WhatsApp Business Account. n8n registers the webhook URL on your app but doesn't subscribe the app to the account. Messages never arrive and n8n shows no error, even though the test event from Meta's dashboard does get through. You check with a GET request to subscribed_apps using the account ID (not the phone number ID) and a token with the whatsapp_business_management permission; if your app isn't listed, a POST request subscribes it. Never send a DELETE: it unsubscribes the app from the account.
    3. The temporary token has expired. The agent stops sending replies.
    4. Your server isn't publishing the right URL. If n8n sits behind a reverse proxy, it can't build the correct URL on its own: set N8N_WEBHOOK_URL and N8N_PROXY_HOPS=1. The old variable, WEBHOOK_URL, has been deprecated since version 2.35.0. Meta also requires a valid TLS certificate and doesn't accept self-signed ones.

    n8n Cloud or self-hosted in the EU?

    n8n Cloud Self-hosted
    Where the data lives In the EU, on servers in Frankfurt Wherever you install it
    Price as of October 2026 Billed annually: Starter, €20 a month and 2,500 executions; Pro, €50 a month and 10,000 executions Community, free; Business, €667 a month billed annually
    Maintenance Handled by n8n Yours: updates, backups and security
    What you configure The credentials and the workflow Also a public URL with a valid certificate and, if you scale in queue mode, a memory other than Simple Memory

    Sources: n8n pricing and choosing between cloud and self-hosted.

    An execution is a single run of the whole workflow, however many steps it has. In a WhatsApp agent, every customer message is at least one execution. If status updates also reach your workflow, each one starts it, even if you discard it in the first node. Do the maths before picking a plan.

    And hosting n8n in Frankfurt doesn't make the whole path European. Meta processes the messages and the AI model provider receives the text of every conversation. You'll find where each provider processes data in the n8n guide.

    What does the law require?

    • Inform people and sign with each processor. The agent handles personal data, so you must inform whoever writes in, as article 13 of the GDPR (RGPD) requires. Meta, n8n if you use its cloud, and the model provider process data on your behalf: article 28 requires you to choose processors with sufficient guarantees and to sign a contract with them.
    • Say it is an AI. Article 50 of the EU AI Act (Reglamento de Inteligencia Artificial) requires that anyone talking to an AI system is told so, unless it is obvious, clearly and at the latest at the first interaction. It has applied since 2 August 2026 (article 113). Put it in the first message and in the system message.
    • Don't turn it into a general assistant. According to Meta's page on AI providers, which refers to its terms updated on 15 January 2026, providers and developers of AI models may only offer general-purpose AI assistants on the platform where Meta is legally required to allow it. The same page says this doesn't change what Meta charges every other business. An agent that serves your customers about your business is a different thing, but keep it focused on your business.

    Would you rather not build it yourself?

    We design and build AI agents and WhatsApp chatbots connected to the tools you already use, with n8n among other tools, data hosted in the EU and no subcontracting. We give a fixed price after a free 2 to 5 day assessment, and a typical automation is up and running in 2 to 4 weeks. More in AI solutions.

    Frequently asked questions

    What session key should the agent's memory use?

    The user ID Meta sends in the user_id field, which incoming messages have always carried since April 2026. The phone number can be missing if the customer uses a username. Never a fixed key: all your customers would share one conversation.

    How many n8n executions does a WhatsApp agent use?

    At least one for every message it receives, because n8n counts each full run of the workflow. If delivered and read updates reach your workflow, they count too. The n8n Cloud Starter plan includes 2,500 executions a month, as of October 2026.

    Can the agent message a customer after 24 hours?

    Only with a template approved by Meta, which in n8n you send with the Send Template operation. That is why you should store the time of each customer's last message and check the window before writing.

    Why does my workflow work in testing but not when I publish it?

    WhatsApp allows one webhook per app, and the test and production URLs overwrite each other. If nothing arrives once published either, check that your app is subscribed to the WhatsApp Business Account with subscribed_apps.

    Do I have to say the agent is an AI?

    Yes. Since 2 August 2026, article 50 of the EU AI Act requires you to say so clearly, at the latest at the first interaction, unless it is obvious. Put it in the agent's greeting.

    Sources

    We check every article against primary sources before publishing it. If you spot a mistake, write to info@quantumnovaagency.com and we will correct it.

    Terms in this article

    Book your free diagnosis.

    Emailinfo@quantumnovaagency.comWhatsApp+34 678 428 710
    LocationTorrevieja (Alicante) · all of Spain

    What happens next

    1. 1We reply within 24 hours.
    2. 2We have a call to look at your case.
    3. 3We send you a proposal with a fixed price.

    By submitting this form you agree to your data being handled under the Privacy Policy.