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. It must not be active on WhatsApp or the WhatsApp Business App — if it is, remove it from the app first, because the app stops working the moment the number moves.

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.

What changes when you go to production

• Your messaging limit applies. New WhatsApp Business Accounts start low and earn higher limits by sending messages people do not block or report — it rises automatically, it is not requested.
• The 24-hour service window applies. Inside a window opened by a customer message you can send freely; outside it you need an approved template.
• 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. Without it you stay capped at the starting tier, which is far below what a campaign needs.

The failures worth pre-empting

Common questions

Related reading