How to set up the WhatsApp Cloud API: the technical walkthrough

The short answer

You set up the WhatsApp Cloud API in six moves: create a Meta app, add the WhatsApp product, register a sender phone number, generate a permanent token from a system user, point a webhook at your server, then send your first message to someone who has opted in. On the free test number the first four take an afternoon.

Two different projects get confused here. Getting *business* access — Meta Business Portfolio, business verification, display name review — is one. Wiring up the *API* — app, token, webhook, endpoints — is the other. This page covers the second. If your business is not yet in a Meta Business Portfolio, do that first.

What you need before you start

• A Meta Business Portfolio — created at business.facebook.com. Your WhatsApp Business Account will live inside it.
• A Meta developer account — a normal Facebook login is enough to reach developers.facebook.com.
• Your business verified — not required to build, but required before you can raise your messaging limit above the starting tier.
• An HTTPS endpoint — somewhere to receive Meta’s webhook callbacks. A serverless function is fine.
• A phone number — for production only. Testing uses a number Meta gives you for free.

The setup, in order

1. 1

   Create a Meta app of type Business

   At developers.facebook.com, create an app and choose the Business type. The consumer app types do not expose the WhatsApp product. Name it something you will still recognise in a year, because the app is the thing your tokens and webhooks hang off.

2. 2

   Add the WhatsApp product to the app

   In the app dashboard, add WhatsApp. Meta immediately provisions a free test number tied to your app plus a temporary access token — that is your sandbox, and it is enough to send real test messages.

3. 3

   Note your identifiers

   You now have a WhatsApp Business Account ID and a phone number ID. Almost every API call addresses the phone number ID, not the phone number itself. Confusing the two is the most common cause of a 404 on the messages endpoint.

4. 4

   Send a test message

   Add up to five recipient numbers in the test configuration, then send a hello-world message through the messages endpoint. This proves the token, the phone number ID and the payload shape all work before you involve a real customer.

5. 5

   Register your production number

   Add your own number to the WhatsApp Business Account and confirm the one-time code. Check what the number is on today before you commit: a number on the regular WhatsApp app cannot be registered to the API, so use a different number, while a number on the WhatsApp Business app can often be connected without deleting anything when the provider supports business-app number onboarding.

6. 6

   Generate a permanent token

   Create a system user in Business Manager, grant it access to the app and the WhatsApp Business Account, and issue a token for it. This replaces the temporary developer token, which expires and is not suitable for anything long-running.

7. 7

   Configure the webhook

   Register a callback URL and a verify token, complete the verification handshake, then subscribe to the message fields you care about. Until the webhook is live you can send messages but you cannot see replies — which makes the integration look broken when it is not.

8. 8

   Submit your first message template

   Messaging someone outside an open 24-hour service window requires a template Meta has approved. Submit one early: approval is asynchronous, so a template submitted on launch day is a launch delayed by a review queue.

The test number: what it does and does not let you do

The free test number Meta gives you is a real sender on the WhatsApp Business Platform. It can send to a small list of recipient numbers you add yourself, and it is the right place to build and debug your integration.

• It is tied to your app, and you can add only a handful of recipient numbers to it.
• Those recipients must be added deliberately — you cannot message an arbitrary number.
• It cannot be used for production traffic, and its messaging limit is not the limit your business will have.
• Moving to a real number does not invalidate your code — only the phone number ID changes.

Why your access token keeps expiring

The token you are shown when you first add the WhatsApp product is a temporary developer token, and it expires. A token that lasts must belong to a system user in Business Manager, not to a person.

A person-owned token dies when that person rotates a password, loses access, or leaves. A system user token is issued to the business itself, so it survives staff changes — which is why every serious integration ends up on one, and why an integration that works in testing mysteriously stops working a day later.

The webhook is where most integrations break

Meta delivers inbound messages and delivery statuses to your webhook by HTTP POST. Getting it right means answering the verification handshake once, then responding to every POST immediately with a 200 while you process the payload asynchronously.

• The verification handshake happens once, when you save the callback URL: Meta sends a challenge and you echo it back with your verify token.
• Every later POST must be answered with a fast 200. If you do the work before replying and it is slow, Meta retries and you get duplicates.
• Validate the signature header on each request so a stranger cannot post fake messages into your system.
• You will receive inbound messages and status callbacks on the same URL — handle both, or you will drop delivery receipts.
• Meta retries failed deliveries, so your handler has to be idempotent. Message IDs are the natural dedupe key.

Which Graph API version to call, and why it matters more than it looks

Every Cloud API call is addressed to a versioned endpoint such as /v25.0/{phone-number-id}/messages, and Meta retires versions on a rolling schedule of roughly two years. Calls to a retired version fail, so the version is a dependency with an expiry date, not a constant.

• Confirm your target version is still supported in Meta’s changelog before you build against it, and before you raise it — raising a version is a code change with behaviour differences attached, not a string edit.
• Keep the version in one place: a single config value every call site reads. A version pasted into each request is how a codebase ends up calling three different versions at once, which is a real and hard-to-see failure mode.
• Expose the version the application actually calls in your health endpoint. A health check that reads the version from the wrong variable tells you nothing during an incident.

What changes when you go to production

• Your messaging limit applies. A new business portfolio starts at 250 unique recipients per 24 hours, shared across every number in the portfolio. Automatic upgrades need high quality and at least half the current cap used in the last seven days — business verification is the faster route up.
• The 24-hour service window applies. Inside a window opened by a customer message you can send any message type without a template; outside it you need an approved template. Since 1 October 2026 those in-window replies are billed per message after 1,000 free service messages per phone number each month.
• Pricing becomes real. Meta bills per delivered template message, priced by category and destination country. Inside an open service window, plain replies and utility templates are treated differently from marketing templates.
• Verification matters more. Business verification is the fast path to a real sending limit, and it is paperwork rather than performance. Without it you stay on the starting tier.

The failures worth pre-empting

Common questions

Related reading