A complete, official, Meta-compliant guide to setting up WhatsApp Cloud API and connecting it to an n8n automation system — for customer support, customer-initiated messaging, and business-initiated messaging. No unofficial tools, no browser automation, no credential sharing.
- 🏗️ Architecture
- 🔒 Security & Compliance
- 🛠️ Stack
- ✅ Prerequisites
- Part A — Create a Business Portfolio
- Part B — Create a Meta Developer Account
- Part C — Create the Meta App
- Part D — Configure Webhooks
- Part E — Add a Payment Method
- Part F — Register a WhatsApp Phone Number
- Part G — Troubleshooting: Registration Failed via Dashboard
- Part H — Generate a Permanent Access Token
- Part I — Create and Host a Privacy Policy
- Part J — Publish the App to Live Mode
- Part K — Set Up n8n to Receive and Send Messages
- Part L — Testing the End-to-End Flow
- Part M — Troubleshooting Common Issues
- 📋 Credentials Checklist
- 👤 Author
| Layer | Components |
|---|---|
| User | Customer sends a message from the WhatsApp app |
| Delivers the message to WhatsApp Cloud, and the reply back to the customer | |
| Meta WhatsApp Cloud API | Receives incoming messages, sends outgoing messages to the recipient |
| Webhook | Sends the event (POST) to your n8n Webhook URL |
| Automation System (n8n) | Receives the webhook, processes data / runs the workflow, saves to DB / calls APIs / AI, generates a reply, sends it back via the Cloud API |
| Delivery & Read Receipts | Status updates flow back to WhatsApp throughout |
- ✅ Official Meta WhatsApp Business Cloud API only — no unofficial tools or browser automation
- ✅ No credential sharing — only Webhooks + a permanent System User Access Token
- ✅ Standard Access — no App Review or Business Verification needed for a single business's own WhatsApp number
- ✅ Access Token is long-lived and secure when generated via a System User
⚠️ A payment method (credit/debit card) must be linked to send messages beyond the free tier — the card is not charged until message volume exceeds it. Customer-initiated conversations within the 24-hour window remain free.
| Component | Role | Purpose |
|---|---|---|
| Meta Business Portfolio | Container | Owns the WhatsApp Business Account (WABA) + App together |
| Meta Developer Account | Access | Required to create and manage the App |
| Meta App (WhatsApp) | Bridge | Connects the phone number to the WhatsApp Cloud API |
| System User + Permanent Token | Credential | Never-expiring token — authenticates all Send API requests |
| Webhook (GET + POST) | Trigger | Meta's verification handshake + incoming message delivery |
| n8n | Automation Engine | Receives the webhook, runs workflow logic, sends replies via the Graph API |
| Payment Method | Billing | Required to register a real number and send business-initiated messages |
| Privacy Policy (public URL) | Compliance | Required before the App can go Live |
- A Facebook account with access to Meta Business Suite
- A real phone number dedicated to the WhatsApp bot (never previously used on the WhatsApp mobile app, or fully deleted from it)
- A running automation system (n8n) on a VPS with a public HTTPS URL (ngrok, Cloudflare Tunnel, or a custom domain)
- A credit or debit card (Visa/Mastercard) to link as the payment method
- A publicly accessible Privacy Policy URL
⚠️ The phone number used for WhatsApp Cloud API cannot simultaneously be used on the WhatsApp mobile app. Once registered with the API, it becomes API-only. Use a dedicated number.
A Business Portfolio (formerly Business Manager) is Meta's container for organizing Pages, Apps, WhatsApp accounts, and other assets. It's required to use WhatsApp Cloud API.
- Go to business.facebook.com and log in with your Facebook account.
- If no portfolio exists, click "Create a Business Portfolio" or "Create Account".
- Enter your business name, your name, and a business email address.
- Click "Submit" / "Next".
- Confirm the email address via the confirmation link Meta sends.
✅ The Business Portfolio name should match your actual business name — it will appear on your WhatsApp business profile.
- Go to developers.facebook.com.
- Log in using the same Facebook account used for the Business Portfolio.
- If prompted, register as a developer: accept the terms, verify with a phone number/SMS code.
- Once registered, you'll land on the "My Apps" dashboard.
- From "My Apps", click "Create App".
- On "App details", enter the App name (e.g.
YourBusiness WA Bot) and select your Business Portfolio. - On "Use cases", click the "Business messaging" filter.
- Select "Connect with customers through WhatsApp" — do not select Messenger or Instagram.
- Click "Next".
- On "Business", select your Business Portfolio.
- Complete "Requirements" and click "Go to Dashboard" / "Create App".
⚠️ The App Dashboard will show a checklist: "Customize the Connect with customers through WhatsApp use case", "Test use cases", and "Check requirements & publish". Click the first item to proceed.
Before adding a phone number, configure the Webhook so Meta knows where to send incoming messages.
- In n8n, create a new workflow (e.g.
WhatsApp Bot). - Add a Webhook node. Set Path to
whatsapp(or any unique path). Set Respond to "Using Respond to Webhook Node". - Add a "Respond to Webhook" node after it.
- Configure:
Respond With= Text,Response Body={{ $json.query["hub.challenge"] }},Response Code= 200. - Save the workflow and toggle it Active.
- Copy the Production URL (e.g.
https://your-domain.com/webhook/whatsapp).
⚠️ Always use the Production URL — not the Test URL. It only works while the workflow is Active.
- In the App Dashboard: Customize the "Connect with customers through WhatsApp" use case → Step 2. Production setup → Configure Webhooks.
- Paste your n8n Production URL into "Callback URL".
- Enter a custom "Verify token" — any secure random string (e.g.
MyVerifyToken2026). Save this value. - Click "Verify and Save".
- On success, a green checkmark appears next to "Configure Webhooks".
Meta auto-subscribes commonly used fields. Verify messages is toggled ON in the Webhook Fields list. Others (account_update, phone_number_quality_update, etc.) can stay default.
Required to register a real phone number and send messages beyond the test sandbox.
- App Dashboard → Step 2. Production setup → find "Add payment to send business-initiated messages".
- Expand it, click "Add payment method".
- You'll be redirected to Meta Business Manager Payment Settings.
- Enter your Visa/Mastercard details and save.
- Return to the App Dashboard — the payment item should show a green checkmark.
✅ The card isn't charged immediately. Charges apply only when business-initiated message volume exceeds the free tier. Customer-initiated conversations within the 24-hour window stay free.
- Go to business.facebook.com/wa/manage/phone-numbers.
- Click "Add phone number".
- Fill in Business information: name, website/profile URL, country. Click "Next".
- Fill in WA Business Profile: Display Name (e.g.
AutomateIQ Labs Support), Category, optional description. Click "Next". - Add the phone number with country code (e.g.
+880Bangladesh,+91India,+1USA). Choose SMS or Voice Call verification. - Enter the OTP. Click "Next".
- Set a 6-digit Two-Step Verification PIN. Write it down — needed for re-registration.
⚠️ The number must not currently be active on the WhatsApp mobile/Business app. If it is, delete the account from Settings → Account → Delete my account inside the app first, then wait 3–5 minutes.
- App Dashboard → Step 2. Production setup → "Register your WhatsApp phone number".
- Click "Register" next to your number.
- Enter the 6-digit PIN from F.1, click "Register".
- On success, status changes to "Registered" with a green checkmark.
- Enable "Subscribe webhooks" next to your number.
If clicking "Register" shows "Registration failed. Please try again." — this is a known issue where the dashboard's register endpoint doesn't work for all account types. Register via a direct API call instead.
- Go to developers.facebook.com/tools/explorer.
- Select your WhatsApp App from the "Meta App" dropdown.
- Under "Add a Permission", add:
whatsapp_business_messagingandwhatsapp_business_management. - Click "Generate Access Token", confirm permissions.
- Copy the generated token.
- In n8n, add an HTTP Request node.
- Method:
POST. - URL:
https://graph.facebook.com/v21.0/{YOUR_PHONE_NUMBER_ID}/register
- Headers:
| Header Name | Value |
|---|---|
Authorization |
Bearer {YOUR_TEMPORARY_ACCESS_TOKEN} |
Content-Type |
application/json |
- Body (JSON):
{
"messaging_product": "whatsapp",
"pin": "YOUR_6_DIGIT_PIN"
}- Execute. Success response:
{ "success": true }. - Check WhatsApp Manager — status should show "Connected".
✅ After successful API registration, return to the App Dashboard and enable "Subscribe webhooks" next to your number.
The Graph API Explorer's temporary token expires in ~1 hour. For production, generate a permanent (never-expiring) token via a System User.
business.facebook.com→ Business Settings (gear icon) → "Users" → "System Users".- Click "+ Add".
- Name it (e.g.
WhatsApp System User), Role = Admin, click "Create system user".
- Click the new System User → "Add Assets".
- Under "Apps", select your WhatsApp App, grant "Full control", save.
- Under "WhatsApp accounts", select your WABA, grant "Full control", save.
- With the System User selected, click "Generate token".
- Select your WhatsApp App.
- Tick permissions:
whatsapp_business_messaging,whatsapp_business_management. - Click "Generate token" — copy it immediately, it's shown only once.
⚠️ Store this token securely in a password manager or your automation system's encrypted credentials store. Never hardcode it in source code or share it in plain text.
- Go to developers.facebook.com/tools/debug/accesstoken.
- Paste the token, click "Debug".
- The "Expires" field should show "Never". If it shows a date, regenerate via System User.
Meta requires a publicly accessible Privacy Policy URL before an App can go Live.
- What data is collected (name, PSID/phone number, message content)
- Why it's collected (customer support, order status, lead handling)
- Whether data is shared with third parties (e.g. AI service providers)
- How long data is retained and how it's protected
- How users can request data deletion, and a contact method
- Notion — publish a page for a public
*.notion.siteURL - Google Sites — build and publish a simple one-page site
- GitHub Pages — host a static HTML file (most reliable for production)
- Your own website, under a
/privacy-policypath
✅ Always test the published URL in an incognito/private window to confirm it's accessible without logging in — Meta checks it this way.
While in Development Mode, only Admin/Developer/Tester accounts can interact with the bot.
- App Dashboard → "App settings" → "Basic".
- Fill in: App Icon (min. 1024×1024px square), Category (
Business and Pages), Privacy Policy URL (from Part I). - Click "Save Changes".
- Click "Publish" in the sidebar.
- Review the use cases, click "Publish" (bottom right).
- App mode changes from "Unpublished" to "Live".
⚠️ Publishing doesn't require App Review or Business Verification for this single-business use case. If Publish doesn't respond, check App settings → Basic for missing required fields.
The Webhook from Part D is already active. Meta sends a POST request shaped like:
{
"entry": [{
"changes": [{
"value": {
"messages": [{
"from": "CUSTOMER_PHONE_NUMBER",
"text": { "body": "Customer message text" }
}]
}
}]
}]
}Extract the sender's number:
{{ $json.body.entry[0].changes[0].value.messages[0].from }}
Extract the message text:
{{ $json.body.entry[0].changes[0].value.messages[0].text.body }}
- Add an HTTP Request node after your automation/AI logic.
- Method:
POST. - URL:
https://graph.facebook.com/v21.0/{YOUR_PHONE_NUMBER_ID}/messages
- Headers:
| Header Name | Value |
|---|---|
Authorization |
Bearer {YOUR_PERMANENT_ACCESS_TOKEN} |
Content-Type |
application/json |
- Body (JSON):
{
"messaging_product": "whatsapp",
"to": "{{ $json.body.entry[0].changes[0].value.messages[0].from }}",
"type": "text",
"text": {
"body": "Your automated reply here"
}
}
⚠️ Thetofield must be the customer's full phone number with country code and no+sign or spaces (e.g.8801700000000).
- Customer sends a WhatsApp message → Meta POSTs to your n8n Webhook URL
- Respond to Webhook node → immediately returns
200 OKto Meta (required within 20 seconds) - Your automation/AI logic → processes the message, generates a reply
- HTTP Request node → sends the reply via the Graph API to the customer's number
- Ensure your n8n workflow is Active.
- From a personal WhatsApp account (not the bot number), message your registered business number.
- Check n8n's Executions tab for a new execution with the incoming message data.
- Confirm the automated reply is received.
- Check App Dashboard → Step 2 → "Send message" — all items should show green checkmarks.
| Symptom | Likely Cause | Fix |
|---|---|---|
| Registration failed via dashboard | Dashboard register endpoint not available for this account type | Use the API registration method (Part G) |
| "Email verification required" generating token | Dashboard token generator requires email verification | Use the System User method (Part H) — no email verification needed |
| Webhook verification fails | Workflow not Active, or Test URL used instead of Production URL | Activate the workflow; use the Production URL |
| No data reaching n8n | Tunnel (ngrok) not running, or number not subscribed to webhook | Check ngrok at 127.0.0.1:4040; enable "Subscribe webhooks" |
success: true but status still Pending |
Dashboard UI cache | Wait 1–2 minutes and refresh WhatsApp Manager |
| Only the bot admin's messages trigger the workflow | App still in Development Mode | Publish the App (Part J) |
| Reply not delivered to customer | to field missing country code, or has a + sign |
Use full number without +, e.g. 8801700000000 |
| Token stopped working | Temporary token used instead of permanent System User token | Regenerate using System User method (Part H) |
Use this checklist for every new client or business onboarded onto the WhatsApp automation system.
| Item | Value / Status | Notes |
|---|---|---|
| Business Name | ||
| Business Portfolio ID | ||
| WhatsApp Business Account ID (WABA ID) | Found in App Dashboard | |
| Phone Number | With country code | |
| Phone Number ID | Found in App Dashboard next to number | |
| Two-Step Verification PIN | Store securely — needed for re-registration | |
| Permanent Access Token | Store securely; confirm "Never" expiry | |
| Webhook Callback URL | n8n Production URL | |
| Webhook Verify Token | The string set in dashboard | |
| Privacy Policy URL | Publicly accessible | |
| App ID | ||
| App Publish Status | Development / Live | |
| n8n Workflow Name | ||
| Payment Method Added | Yes / No |
