How to connect WhatsApp Cloud API to n8n (Meta app, token and webhook)

Before you build a WhatsApp AI agent, n8n and WhatsApp Cloud API need to talk to each other. That connection is where most beginners get stuck: the Meta app, the token, the Phone Number ID and an HTTPS webhook Meta can reach.

This guide covers only that piece: create the app, grab the credentials, register the webhook in n8n, verify the token and receive a test message. Once that works, you can import the free agent template.

What you will connect

A Meta app (Business type) with the WhatsApp product.
An access token (temporary at first) and the Phone Number ID.
A Webhook node in n8n with a public HTTPS URL.
Webhook verification (Meta’s challenge) and the first inbound message.

What you need

n8n with a public HTTPS URL (n8n Cloud, or self-hosted behind a tunnel/server). Plain localhost is not enough: Meta cannot call your laptop. If you do not have n8n yet, start with install n8n for free.
A Meta for Developers account (developers.facebook.com).
About 30–45 minutes the first time.

Step 1: create the Meta app

Open Meta for Developers → My Apps → Create App.
Choose type Business (or the current equivalent business flow).
Give it a clear name (AgentKiosk-Test is fine) and link a Business Portfolio if asked.
Inside the app, go to Add products and add WhatsApp.

Under WhatsApp → API Setup you will see the test number, the Phone number ID, the WhatsApp Business Account ID and a button to generate a temporary token.

Copy now:

Phone number ID (not the human-readable number on screen; the long numeric ID).
Temporary access token (expires in hours; for testing only).

Step 2: the webhook in n8n

Create a new workflow.
Add a Webhook node.
Method: POST. Path: something short, for example whatsapp.
Respond immediately with 200 (or use “Respond Immediately”) so Meta does not retry.
Activate the workflow (or use the test URL for your n8n version) and copy the production HTTPS URL.

That URL must be reachable from the internet. Without HTTPS, Meta rejects the registration.

Step 3: register and verify the webhook in Meta

In WhatsApp → Configuration (or API Setup → Webhook):

Callback URL: the HTTPS URL of your Webhook node.
Verify token: invent a secret string (for example ak_verify_2026) and store the same value in n8n.
Meta will send a GET with hub.mode, hub.verify_token and hub.challenge. Your flow (or the Webhook node in verify mode) must return the challenge as plain text when the token matches.
After verification, subscribe to the messages field.

If verification fails, it is almost always: URL not HTTPS, inactive workflow, or a verify-token mismatch (even one character).

Step 4: receive the first test message

In API Setup, add your personal number to the test recipient list.
From the Meta panel (or curl/Postman) send a hello/template to the test number, or message the test number from your WhatsApp.
In n8n, listen with the workflow active and inspect the inbound JSON: entry[0].changes[0].value.messages[0] usually holds the text and the client from.
To reply, use an HTTP Request node (or a WhatsApp node if you have one) against the Graph API with the token and Phone Number ID.

A minimal echo (“got it”) proves the round trip before you wire up AI.

Temporary token vs permanent token

	Temporary	Permanent (System User)
Expiry	Hours	Until you rotate / revoke it
Use	Testing only	Production
How	Button in API Setup	Business Settings → System Users → Generate token with `whatsapp_business_messaging` and `whatsapp_business_management`

Store the permanent token as an n8n credential, never in a visible Set node. If sending suddenly stops, check token expiry first.

Test number vs real Business number

Meta test number: free, ideal for learning. You can only message a few allowlisted numbers. Not for real customers.
Your own Business number: connect it once the flow replies reliably. It means a verified business under Meta’s current rules and a number that is not stuck in a conflicting WhatsApp Business account.

Practical rule: develop on the test number; move to a real one only when the webhook, anti-loop filters and message typing are stable.

Common errors

Webhook will not verify. HTTPS required; workflow active; verify token identical; return the challenge in the body, not HTML.
“Invalid OAuth access token”. Temporary token expired or pasted with spaces/quotes.
Send fails / recipient error. You are on the test number and the phone is not on the tester list.
Wrong Phone Number ID. You mixed it up with the WABA ID or the readable +1… number. The Graph API URL needs the Phone number ID.
Double replies / loops. You are reacting to echoes of your own sends or to statuses (delivered, read). Filter: only process client text messages, not statuses.
Local n8n with no tunnel. Meta will never reach http://localhost:5678. Use Cloud, a VPS or a tunnel with WEBHOOK_URL set correctly (more in the install guide).

Honest limits

Meta’s UI renames menus often; if you cannot find “API Setup”, open WhatsApp inside the app and look for webhook configuration.
The test number is not a real support channel.
Connecting the API ≠ a good agent: you still need memory, a business prompt, media filters and human handoff. That is covered in the agent guide and the free template.

Next step

With the webhook verified and a test message visible in n8n, download the free WhatsApp agent and import it. If you still need n8n, install it step by step. For the full agent pack, see the AgentKiosk pack.