WhatsApp Cloud API — Manual Setup (Single WABA, no Tech Provider needed)

This guide is for the typical CodeCanyon buyer who wants to send WhatsApp messages from their own WhatsApp Business Account (WABA) — without becoming a Meta Tech Provider or BSP. Total setup time: about 5 minutes.

When to use Manual Setup vs Embedded Signup:

Manual Setup (this article) — you have one WABA and you want to send from it. No Meta approval needed. Works today.

Embedded Signup (the "Connect via Embedded Signup" button) — only available to Meta-approved Tech Providers / BSPs. If you see the error "Embedded signup is only available for BSPs or TPs", your app is not Tech Provider approved — use Manual Setup instead.

What you need before you start

A Meta App (developers.facebook.com → My Apps) linked to your Meta Business Manager.
A verified WhatsApp Business Account (WABA) inside that Business Manager, with at least one phone number registered.
Admin role on the Business Manager.

You do NOT need: Tech Provider approval, App ID, App Secret, App Review, or a Configuration ID.

Step 1 — Generate a long-lived System User Access Token

Open business.facebook.com/settings.
Go to Users → System Users → click Add.
Name: XSender API. Role: Admin. Click Create System User.
Click the new System User → Generate New Token.
Select your Meta App.
Tick these two permissions: whatsapp_business_management, whatsapp_business_messaging.
Token Expiration: Never.
Click Generate Token. Copy the token immediately — it begins with EAAB... and Meta will not display it again.

Step 2 — Assign your WABA to the System User

Still in Business Manager → Accounts → WhatsApp Accounts.
Click your WABA → Add People / Assign.
Select the XSender API System User → permission: Full Control → Assign.

Without this step the token cannot send messages from your WABA — even though it's a valid token.

Step 3 — Find your two IDs

Open developers.facebook.com/apps → your App → WhatsApp → API Setup. The page shows:

Phone Number ID — a long number next to your WhatsApp display number.
WhatsApp Business Account ID (also called WABA ID) — shown above the phone number.

Copy both.

Step 4 — Add the gateway in XSender

Open Admin Panel → Gateway → Messaging Gateways → WhatsApp Cloud APIs.
Click the Add Manually button at the top-right.
Fill in the modal:
- Business Portfolio Name — a friendly name, e.g. Production Number.
- Per Message Minimum Delay (seconds) — 0.5 is a safe default.
- Per Message Maximum Delay (seconds) — 2.
- Delay After Count — 50.
- Delay After Duration (seconds) — 5.
- Reset After Count — 200.
- User Access Token — paste the EAAB... token from Step 1.
- Phone Number ID — from Step 3.
- WhatsApp Business Account ID — from Step 3.
Click Save. The gateway appears in the list with status Active.

The rate-limit fields above are conservative defaults. Increase them once you have warmed up your number with real traffic. Lower means slower but safer; higher means faster but more likely to trip WhatsApp's anti-spam.

Step 5 — Configure the Meta webhook (one-time)

This is required for delivery + read receipts to appear in XSender.

Open the XSender WhatsApp Cloud APIs page — note the two values shown at the top: Webhook Callback URL and Webhook Verify Token.
In Meta Developer Portal → your App → WhatsApp → Configuration → Webhooks → click Edit.
Paste the Callback URL and Verify Token from XSender into Meta's fields. Click Verify and Save.
Click Manage next to Webhook fields and subscribe to these events:
- messages — receive incoming messages.
- message_status — delivered + read receipts.
- message_template_status_update — template approvals.

Step 6 — Send a test message

Communication → WhatsApp → Send.
Pick the new gateway from the dropdown.
Enter your own WhatsApp number (in international format, e.g. +15555550123).
Body: "Hello from XSender".
Click Send. The message should arrive on your phone within 1–2 seconds.
The dispatch log in XSender will flip pending → sent → delivered → read (once you open the message on your phone).

Troubleshooting

Symptom	Likely cause	Fix
"Embedded signup is only available for BSPs or TPs"	You clicked the wrong button	Use Add Manually, not Connect via Embedded Signup.
Save returns "Invalid OAuth access token"	Token was copied incompletely, or the System User was not assigned to the WABA	Re-generate the token (Step 1) and confirm the WABA assignment (Step 2). Tokens are usually 200+ characters.
Send returns "(#100) The parameter messaging_product is required"	Phone Number ID belongs to a different WABA, or the number is not yet registered	Re-check Step 3 values in Meta Developer Portal → WhatsApp → API Setup.
Send returns "Recipient phone number not in allowed list"	Your Meta App is in Development mode	Meta Developer Portal → your App → App Mode → switch to Live. Note: requires a Privacy Policy URL.
Webhook verification fails in Meta	Callback URL not reachable, or Verify Token mismatched	Confirm `https://yourdomain/api/whatsapp/webhook` returns 200 in a browser. Re-copy the Verify Token exactly — no leading/trailing spaces.
Status stays at `sent`, never advances to `delivered` or `read`	Webhook not configured, or required fields not subscribed	Re-do Step 5 and tick `message_status`.

After setup — what to do next

Approve message templates for marketing / utility outbound campaigns: Admin Panel → Templates → WhatsApp → Create. Meta must approve them before you can use them in campaigns.
Warm up your number — send low volume (50–100 messages/day) for the first 2 weeks. Higher quality rating = higher daily limit.
Set up the Auto-Reply Bot — sidebar → Automation Workflows → WhatsApp Auto-Reply Bot.
Configure the WhatsApp Node service (optional) if you also want to send from a personal WhatsApp number (not Business API). See: Gateway → WhatsApp Node Service Setup.

What this setup does NOT use

App ID + App Secret — only required for Embedded Signup (Tech Provider mode). Single-WABA Manual Setup does not need them.
Meta Configuration entry (the screen at Admin → Settings → WhatsApp Configurations) — only required if you want to onboard end-customers via Embedded Signup. Manual Setup writes the token directly onto the gateway.
Tech Provider approval — the multi-week Meta application process. Not needed for sending from your own WABA.