How to Set Up WhatsApp Cloud API: Step-by-Step 2026 Guide

What you need before you start

The fastest setup is the one where you know which Meta business, app and phone number should own the integration before you start clicking through dashboards.

How to set up WhatsApp Cloud API, step by step

This flow follows the direct developer route. Meta changes dashboard labels from time to time, so focus on the asset you are creating rather than the exact button wording.

1. Create or select the correct Meta Business Portfolio

   Use the portfolio that should own the WhatsApp Business Account and production number. Check the legal business information before attaching production assets so you do not build under the wrong business.

2. Create a Meta app for WhatsApp business messaging

   Open Meta for Developers, create an app, and choose the WhatsApp or business-messaging use case shown in your dashboard. Associate the app with the correct business portfolio when prompted.

3. Connect or create the WhatsApp Business Account

   Inside the WhatsApp setup flow, connect the WABA that will own your messaging assets. Write down the WABA ID and Phone Number ID shown in the API setup area.

4. Use Meta's test number before touching production

   Meta's onboarding flow provides test assets so you can confirm the API request, recipient format and token before registering your live number. This is the safest place to catch configuration mistakes.

5. Send the first test message

   Use the temporary token and the test Phone Number ID to send Meta's test template to a recipient you have added for testing. Once this succeeds, you know the basic app-to-WhatsApp connection works.

6. Plan the production phone-number path

   Before registering a business number, confirm whether your account will use a new number, a migration flow, or a supported coexistence path. Availability can vary by account and onboarding route, so do not remove a busy production number from the WhatsApp Business App until the migration path is confirmed.

7. Create a system-user token for production

   Temporary tokens are for testing. For production, create the appropriate system user in Meta Business Settings, assign the required app and WhatsApp assets, generate the permissions required by your integration, and store the token only on your server or secret store.

8. Configure the webhook

   Add a public HTTPS callback URL and your own verification token. Subscribe to the message events your application needs, then test both inbound messages and delivery/read status events.

9. Run a production-readiness check

   Confirm the correct business owns the WABA, the live number is connected, the token works, webhook events arrive, templates are available for the messages you intend to send, and secrets are not exposed in browser code or source control.

Official reference: Meta WhatsApp Business Platform — Get Started . Meta can change onboarding screens and requirements, so use the current dashboard as the final source of truth for your account.

Send your first WhatsApp Cloud API message

A successful first request proves three things at once: your token is accepted, the Phone Number ID is correct, and the recipient/test configuration is valid.

Use the currently supported Graph API version shown in Meta's documentation. Keep the version explicit in production code instead of relying on an unversioned endpoint.

curl -X POST \
  "https://graph.facebook.com/<GRAPH_API_VERSION>/<PHONE_NUMBER_ID>/messages" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "<RECIPIENT_NUMBER>",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": {
        "code": "en_US"
      }
    }
  }'

If Meta returns a message ID, store it. Your webhook can later receive status events tied to that message, which is how your application tracks delivery and read-state updates.

Temporary token vs production access token

A system-user token is often called a “permanent access token” in setup guides, but it can still be revoked or invalidated. Never place a production token in frontend JavaScript, a public repository, a screenshot, or a client-side mobile bundle. Treat it like a server secret. If a token is exposed, rotate it and review the associated app and business permissions.

Set up the WhatsApp webhook correctly

Sending is only half of a WhatsApp integration. Webhooks are how your application receives customer messages and message-status events.

Webhook verification

Meta sends a verification request to your callback URL. Your endpoint must compare the verification token with the value you configured and return Meta's challenge when the values match.

Webhook events

After verification, subscribe to the message-related fields your application needs. Your backend should acknowledge valid webhook requests quickly, then move heavier processing into a queue or worker.

Production webhook checklist

• Public HTTPS URL with a valid certificate
• Separate verification token that is not your Meta access token
• Fast HTTP 200 acknowledgement for valid events
• Idempotent processing so retries do not create duplicate actions
• Logging for message IDs, timestamps and status transitions
• Secrets stored outside source code

Where Meta Business Verification fits into the setup

Business verification is important, but it should not be presented as if every development step is blocked until verification is finished.

Meta provides test assets during developer onboarding, which lets you begin the technical integration before every production requirement is complete. Business verification, messaging eligibility and the documents Meta asks for can vary by account, business type, market and onboarding route.

If you serve several markets—Pakistan, UAE, India, UK, USA, Bangladesh or Australia—keep the technical Cloud API steps the same and localize only the business-verification guidance that can be supported by current Meta instructions for that market.

Direct Meta setup vs a Meta Verified Tech Provider

The underlying WhatsApp Cloud API is the same. The difference is how much of the onboarding, software layer and day-to-day tooling your team wants to build and maintain.

On Cloud API is positioned as a Meta Verified Tech Provider, not as a reseller BSP. If you want the official Cloud API without manually managing the full dashboard/token/webhook setup, see the On Cloud API WhatsApp Cloud API page .

Common WhatsApp Cloud API setup errors

1. The access token suddenly stops working

You are probably still using a temporary setup token. Confirm the token type, app, system user and assigned WhatsApp assets.

2. The API request uses the wrong ID

The messaging endpoint needs the Phone Number ID. Developers often paste the WABA ID or the visible phone number into the endpoint by mistake.

3. The webhook verifies but no messages arrive

Check that the app is subscribed to the correct WhatsApp Business Account and the required webhook fields. Also confirm your production URL—not a temporary local test URL—is active.

4. A production number cannot be registered

Check whether the number is already attached to another WhatsApp account or onboarding path. If the number is business-critical, confirm migration/coexistence eligibility before removing it from an existing setup.

5. Test messages work but business-initiated messages fail

Testing and production messaging have different conditions. Check the recipient, template availability, message category, account status and the current rules shown in WhatsApp Manager before treating it as an API-code failure.

Production checklist before you go live

• Correct Meta Business Portfolio owns or manages the required WhatsApp assets
• WABA ID and Phone Number ID are recorded separately
• Production number is registered through the intended migration/coexistence path
• System-user token is stored server-side in a secret manager or protected environment variable
• Webhook is public, HTTPS and subscribed to required events
• Webhook processing is idempotent and queue-friendly
• Templates needed for business-initiated messaging are ready
• Opt-in and messaging-policy requirements are built into the workflow
• Error logging captures Meta response codes and message IDs
• Your team has a process for token rotation, access reviews and API-version upgrades

Does WhatsApp Cloud API setup change by country?

The technical architecture—Meta app, WABA, phone number, token, Graph API and webhook—is broadly the same. What can differ is business-verification evidence, local billing and country-specific operational or regulatory requirements.

For Pakistan-specific pricing and onboarding context, read the WhatsApp Business API in Pakistan guide . For other markets, keep the setup guide technical and link to a dedicated local page instead of stuffing seven different document lists into one tutorial.

Frequently asked questions