How to get WhatsApp Cloud API — the complete setup manual

Getting WhatsApp Cloud API from Meta is genuinely complicated. Most tenants hit at least 2-3 dead-ends before they're sending their first message — phone numbers stuck in "already in use" loops, display names rejected for being too generic, tokens that expire after 60 days, tier caps that won't lift without business verification. Meta's docs assume you already know all of this.

This guide walks the Meta-side prerequisites end-to-end. Once you have your credentials, plug them into Botline at /dashboard/integrations and Botline takes over — webhook setup, AI agent, broadcast composer, catalog commerce, opt-out detection, health monitoring — all of it.

Active work: 1.5-2 hours. Wall time: 1-7 days (the bottleneck is Meta's display-name review and business verification queue).

📄 Download the printable PDF version — same content, A4 format, take it to your IT team or print it for offline reference.

You need these things ready BEFORE you start. Skip ahead and you'll get blocked halfway through.

Legal business identity

A real business — sole proprietor, registered company, or trade license. Personal name accounts get rejected. Have your business name + registration document handy.

A "clean" phone number

This is the #1 reason tenants get stuck. The phone number you'll use for Cloud API:

• Must NOT currently have a personal WhatsApp account on it, OR
• You must be willing to delete (not log out) the personal WhatsApp account before connecting it to Cloud API

To delete a personal WhatsApp account on a number: open WhatsApp on the phone → Settings → Account → Delete my account → enter phone number → confirm. ⚠️ This is destructive. Backup chats first via Settings → Chats → Chat backup if you want to keep history.

After deletion, wait 5-10 minutes before adding the number to Meta — their records take a few minutes to clear.

Facebook personal account + business email + a simple website

You (the human admin) need a personal Facebook account (Meta ties Cloud API to a Business Manager which requires one). A business email under your own domain speeds up Meta review. A public website — even a one-page Squarespace / Wix / Notion-public-page — helps display-name approval.

If you have 2-factor authentication on the Facebook account and hit a sign-in loop during Meta onboarding: temporarily disable 2FA, complete signup, re-enable after.

1. Go to business.facebook.com
2. Click Create Account (top right)
3. Enter business name (your real legal name), your name, business email
4. Click Next, add address + phone + website + time zone + currency
5. Verify your business email — open the verification email Meta sends and click the link

You now have a Business Manager. Bookmark it — you'll be back often.

The WABA is the container for your phone numbers + display name + catalog.

1. Inside Business Manager → left sidebar → Accounts → WhatsApp Accounts → Add → Create new WABA
2. Enter:
   • Display name — what your customers see in WhatsApp. Pick a real-business specific name. Generic names ("Customer Care", "Support", "Help Desk") get auto-rejected. Examples that work: "Fone Pro PK", "Hadeed Farms", "Dr. Afshan Hamdani".
   • Business category — pick the closest one
   • Description + Profile picture (your logo, square, ≥500x500 px)
3. Click Create

The WABA is now in "Pending" review for the display name. You can still proceed to Phase 3 — display name review happens in parallel and finishes within minutes-to-days.

Most tenants fail here on the first try. Get Phase 0.2 right and this works first time.

1. Inside Business Manager → WhatsApp Accounts → click your WABA
2. Top tab: Phone numbers → Add phone number
3. Choose hosting: Hosted by Meta (Cloud API) — ⚠️ NOT "Hosted by you (On-Premises)" — that's a different product, expensive, requires self-hosting
4. Enter the phone number from Phase 0.2
5. Pick OTP delivery: SMS or Voice call. If SMS doesn't arrive within 2 minutes, retry with Voice.
6. Receive the OTP, enter it

If Meta says "phone number already in use"

Usually means: the number had personal WhatsApp before, you forgot to delete (not just log out), OR Meta hasn't propagated the deletion yet. Fixes:

1. Confirm personal WhatsApp is genuinely deleted (Phase 0.2 steps)
2. Wait 30 minutes
3. Retry with Voice call OTP instead of SMS
4. If still failing, try a different SIM or number — some carriers in Pakistan / South-East Asia block Meta SMS

Two paths — pick one.

Path A: Embedded Signup (smoother)

Works when Botline's Meta App Review approval is finalized. Once approved, the "Sign up with Facebook" button appears in /dashboard/integrations. Click it → log in → grant permissions → token auto-flows to Botline. Skip Path B.

Path B: Manual System User Token (works today)

Slightly more steps; same result.

1. Create a System User: Business Settings → Users → System Users → Add → name it "Botline API" → role Admin
2. Assign WABA permissions: click new System User → Add Assets → WhatsApp Accounts → pick your WABA → toggle Full Control ON → Save
3. Generate token: click Generate New Token → pick scopes whatsapp_business_messaging + whatsapp_business_management → expiry: Never ⚠️ critical, default is 60 days → click Generate
4. Copy the token immediately — Meta shows it ONCE. It looks like EAAxxxxxx... (~200 chars).
5. Get the IDs: from WhatsApp Manager grab Phone Number ID + WABA ID + (optional) Business Account ID
6. Plug into Botline: /dashboard/integrations → Add Cloud API line → I have credentials tab → paste 4 fields → Test connection → Save

Line is now live. You can immediately send/receive messages, author Meta-approved templates, build broadcast campaigns, use interactive buttons / lists / catalog commerce, and monitor health at /dashboard/whatsapp/health.

Happens automatically — you just wait + check. Status flow:

• Pending — review in progress. You can send messages but show as unverified.
• Approved — green badge, full features.
• Rejected — your display name didn't match Meta's policies.

Common rejection reasons: generic words ("WhatsApp", "WA", "Help", "Customer Care"), implies you're Meta or another company, doesn't match your actual business name, profanity or competitive references. If rejected: change the name (back in Phase 2) and resubmit. Each resubmit = fresh review.

Required if you want to send to >250 unique recipients per 24 hours. Without it: stuck at Tier 250 forever.

1. Business Manager → Settings → Security Center → Business Verification
2. Submit: certificate of incorporation OR business registration, recent utility bill in your business name, bank statement (optional, speeds review)
3. Pick verification method: phone, email, or domain
4. Submit → Meta reviews → emails you when done (1-7 business days)

With verification approved, the tier ramp opens up to TIER_1K → TIER_10K → TIER_100K → unlimited based on your messaging quality.

Tier ramp

Tier	Limit
Tier 50	50 unique recipients per 24h
Tier 250	250 unique recipients per 24h
Tier 1K	1,000 unique recipients per 24h
Tier 10K	10,000 unique recipients per 24h
Tier 100K	100,000 unique recipients per 24h
Unlimited	No cap

Climb by sending messages customers respond to + don't get blocked. Meta promotes after 7 consecutive days of good behavior.

Quality rating (Green / Yellow / Red)

• 🟢 GREEN — healthy, send freely
• 🟡 YELLOW — watch list, Meta is monitoring; continued issues → demote
• 🔴 RED — throttled, send volumes drop; continued issues → BLOCKED (terminal — can't recover)

To stay GREEN: don't broadcast outside the 24h window without approved templates, don't send to numbers that haven't engaged, honor opt-outs immediately (Botline does this automatically), personalize templates instead of mass-blasting identical text.

Stuck on	Fix
"Phone number already in use"	Delete (not logout) personal WA on the SIM. Wait 30 min. Retry with voice OTP.
Display name rejected	Make it specific to your real business. Drop "support" / "service" / "help" / "WhatsApp". Resubmit.
2FA loop on Facebook	Temporarily disable 2FA. Complete signup. Re-enable after.
Token expired after 60 days	Re-generate with Never expiry via System User token. Update in Botline.
Stuck at Tier 250 forever	Submit Business Verification documents (Phase 6). Wait 1-7 days. Tier opens.

Once you've completed Phase 5 and pasted credentials into Botline, the platform handles:

• Automatic webhook configuration — Botline subscribes to Meta's events for you
• AI-powered conversations — your customers chat with the AI 24/7
• Template authoring + Meta submission — write templates inside Botline, submit with one click
• Broadcast campaigns — segmented audiences, delivery analytics, cost preflight
• Interactive messages — buttons, lists, location requests, vCards, product carousels
• Catalog Commerce — multi-product carousels from your Shopify or WooCommerce catalog
• Health monitoring — quality rating, messaging tier, opt-out management at /dashboard/whatsapp/health
• STOP keyword detection — automatic compliance with global opt-out norms
• WhatsApp Flows — multi-screen interactive forms for booking / lead capture / surveys (coming soon)

You don't need to know the Meta API to use any of this — Botline talks to Meta on your behalf.

📄 Download this guide as PDF for offline reference or to share with your IT team.