WhatsApp Business API & Cloud API
How to Set Up WhatsApp Cloud API Step by Step
Set up the official WhatsApp Cloud API from Meta app creation through business phone configuration, messaging, webhooks, and production access.
Before You Begin
What You Need Before Setting Up WhatsApp Cloud API
You do not need to have every WhatsApp API credential ready before starting. Some important assets and identifiers are created or connected while you go through the Meta setup.
Before beginning, make sure you have access to the Meta account, business, phone number, and development environment you plan to use for the integration.
Meta Account
You need a Meta account that you can use with Meta for Developers to create and manage the application used for your WhatsApp Cloud API integration.
Meta Business Portfolio
Your WhatsApp Business Account and other business assets are connected with a Meta business portfolio. Make sure you have access to the correct business before starting.
Business Phone Number
You will need a phone number for your WhatsApp Business Platform setup. If you are only testing initially, Meta also provides test resources during the development setup.
Backend or Development Environment
You need somewhere to make API requests and later process WhatsApp events. This can be a Node.js, Python, PHP, or other backend application capable of making HTTPS requests.
Public HTTPS URL for Webhooks
When you reach the webhook part of the setup, your backend needs a publicly accessible HTTPS endpoint so Meta can verify it and send WhatsApp events to your application.
Access to Meta Business Settings
You should have sufficient access to the business assets you plan to use, especially when configuring the WhatsApp account, phone number, system users, and production permissions.
You Do Not Need a Production Access Token Yet
During the initial setup, you can use the development resources provided through the WhatsApp Getting Started area. We will deal with production credentials, system users, permissions, and long term access later in this guide.
Step 1
Create Your Meta Developer App
Your Meta app is the application that connects your backend with the WhatsApp Business Platform. It contains the WhatsApp product configuration, API credentials, webhook settings, and permissions used by your integration.
Start by creating a Meta app specifically for the business or application you are connecting to WhatsApp.
Open Meta for Developers
Sign in to Meta for Developers with the Meta account that will manage your WhatsApp integration. Complete the developer registration process if Meta asks you to do so.
Create a New App
Open My Apps and choose Create App. When Meta asks what you want your app to do, select the WhatsApp or business messaging use case. If your dashboard shows app types instead, choose a Business app type that supports WhatsApp.
Enter Your App Information
Give the application a clear name and provide the requested contact information. Use a name that will still make sense later when you have multiple Meta applications.
Connect Your Business Portfolio
When Meta gives you the option, select the Meta business portfolio that will own or manage the WhatsApp Business Account and phone number used by this integration.
Meta Dashboard May Look Slightly Different
Meta regularly changes the app creation interface. Some accounts may see a WhatsApp use case first, while others may see an app type selection. The goal is the same: create an app that supports the WhatsApp Business Platform and associate it with the correct business.
Step 2
Add WhatsApp to Your Meta App
Once the Meta app exists, the next step is connecting the WhatsApp Business Platform to it. This gives the application access to the WhatsApp specific setup, messaging configuration, business assets, and webhook settings.
Open Your Meta App
Go to My Apps in Meta for Developers and open the application you created for your WhatsApp integration.
Add the WhatsApp Product
Find WhatsApp in the app products or use cases area and choose the option to configure or set it up. If WhatsApp was already added when you created the app, continue to the next step.
Connect Your Business
Select the Meta business portfolio that should be connected with the WhatsApp setup. Meta can create the WhatsApp Business Account and development assets required for testing during this process.
Open WhatsApp API Setup
After setup, open the WhatsApp section of your app dashboard and look for API Setup or Getting Started. This is where you will find the test phone number, access token, Phone Number ID, and WhatsApp Business Account information.
Keep the IDs Separate
The Phone Number ID is not your actual telephone number, and the WhatsApp Business Account ID is another separate identifier. You will use these IDs for different API operations later in the integration.
Step 3
Test WhatsApp Cloud API With Meta's Test Number
Before connecting your real business phone number, use the development resources provided by Meta to confirm that your application can successfully send a WhatsApp message through the Cloud API.
Use Meta's Test Phone Number
In WhatsApp API Setup, Meta provides a test WhatsApp number that you can use while developing the integration. You do not need to connect your real business number yet.
Add a Recipient Number
Use the recipient section in API Setup to add the WhatsApp number that should receive your test message. Complete the verification Meta requests for that recipient.
Copy the Temporary Access Token
Copy the temporary access token shown in the API Setup area. This token is useful for development testing but should not be used as your production credential.
Send the Test Message
Use Meta's test message controls or make the API request yourself. If the setup is correct, the recipient phone should receive the WhatsApp message.
Test the API Directly
You can also send the test message directly from your terminal. Replace the placeholders with the values shown in your WhatsApp API Setup page.
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_PHONE_NUMBER>",
"type": "text",
"text": {
"body": "Hello from WhatsApp Cloud API"
}
}'Temporary Token Is for Development
The access token available in the WhatsApp API Setup area is useful for testing, but it expires. Later in this guide we will create the credentials needed for a production integration.
Step 4
Add Your Business Phone Number
Once messaging works with Meta's test number, you can connect the real business phone number that your application will use to communicate with customers.
This number becomes an important WhatsApp Business Platform asset, so make sure you are adding it to the correct WhatsApp Business Account and Meta business portfolio.
Start Adding a Phone Number
From the WhatsApp setup or WhatsApp Manager, choose the option to add a real business phone number instead of using Meta's development test number.
Enter Your Business Information
Complete the requested WhatsApp business profile information. Meta may ask for details such as the business display name, category, description, and website.
Enter the Business Phone Number
Enter the phone number you want to use with the WhatsApp Business Platform. Make sure you have access to the number because Meta needs to verify that you control it.
Verify Phone Ownership
Choose one of the verification methods offered by Meta, such as SMS or voice verification, and enter the code you receive to confirm ownership of the phone number.
Configure Two Step Verification
WhatsApp Cloud API registration requires two step verification. When required during registration, create and securely store the six digit PIN associated with the business phone number.
Already Using This Number on WhatsApp?
Do not assume that an existing WhatsApp number can always be connected directly. Depending on how the number is currently registered and the setup available to your business, Meta may require a migration or another supported onboarding process. Check the status of the number before removing or changing an existing WhatsApp setup.
Step 5
Find Your WABA ID & Phone Number ID
A WhatsApp Business Account ID and a Phone Number ID identify two different objects. The WABA ID identifies the WhatsApp Business Account. The Phone Number ID identifies the specific business phone number that sends messages through the Cloud API. Keep both values in your server configuration because different Graph API endpoints expect different IDs.
You can see these values in the WhatsApp API setup area, and you can also retrieve phone numbers connected to a WABA through the Graph API. Do not use the visible telephone number where an endpoint expects a Phone Number ID. That mix-up is one of the most common causes of an object not found or unsupported request error.
Implementation Checklist
- Save the WABA ID in an environment variable such as WHATSAPP_WABA_ID.
- Save the sending number's Phone Number ID separately, for example WHATSAPP_PHONE_NUMBER_ID.
- Confirm that the IDs belong to the same business and app you are configuring.
- Never expose these identifiers together with access tokens in browser code or public logs.
Retrieve phone numbers connected to a WABA
curl -X GET \
"https://graph.facebook.com/<GRAPH_API_VERSION>/<WABA_ID>/phone_numbers" \
-H "Authorization: Bearer <ACCESS_TOKEN>"Step 6
Create a Production Access Token
The temporary token shown in the WhatsApp API setup screen is useful for initial testing, but a production integration should use a system user access token managed from the correct Meta business. This keeps the credential tied to business assets instead of depending on a developer's short lived user token.
Create or use a system user in Business Settings, assign the WhatsApp Business Account and phone number assets it needs, then generate a token for the app with the required WhatsApp permissions. For messaging, the important permissions normally include whatsapp_business_messaging, and management operations can also require whatsapp_business_management. Give the system user only the assets and permissions your integration actually needs.
Implementation Checklist
- Create or select a system user under the correct Meta business.
- Assign the WhatsApp Business Account and relevant assets to that system user.
- Generate the token for the same Meta app used by the integration.
- Store the token only on the server, preferably in a secret manager or protected environment variable.
Important
After creating the token, test it with one simple API request before wiring it into the rest of the application. This makes permission and asset problems much easier to isolate.
Step 7
Send Your First WhatsApp Cloud API Message
Outbound messages are sent from your server to the Graph API messages endpoint for the sending Phone Number ID. Authenticate with a bearer token, validate the recipient and payload, and store the returned WhatsApp message ID so later webhook statuses can update the correct record.
Implementation Checklist
- Send from server side code, never expose the token in the browser.
- Use the Phone Number ID in the endpoint path.
- Persist the returned message ID for status tracking.
This guide only covers the part needed for the current workflow. For the complete setup, examples, and troubleshooting, continue with How to Send a WhatsApp Message With Cloud API.
Step 8
Set Up Your WhatsApp Webhook
Webhooks are the event input for a WhatsApp integration. Meta verifies a public HTTPS callback URL, then sends incoming messages and message status events to that endpoint. Your app also needs the correct WhatsApp Business Account subscription so events reach the callback.
Implementation Checklist
- Use a public HTTPS callback and a separate verify token.
- Subscribe the app to the correct WABA and required webhook fields.
- Acknowledge events quickly and process them idempotently.
This guide only covers the part needed for the current workflow. For the complete setup, examples, and troubleshooting, continue with How to Set Up WhatsApp Webhooks.
Step 9
Subscribe Your App to the WhatsApp Business Account
Configuring the webhook callback URL is not enough by itself. Your Meta app also needs to be subscribed to the WhatsApp Business Account, commonly called the WABA, so events for the phone numbers under that account are delivered to the webhook you configured.
The subscription uses the WABA ID, not the Phone Number ID. After the subscription succeeds, send a known message to the business number and confirm that your webhook receives the event before you connect chatbot, CRM, or automation logic.
Subscribe the App
curl -X POST \\
"https://graph.facebook.com/<GRAPH_API_VERSION>/<WABA_ID>/subscribed_apps" \\
-H "Authorization: Bearer <ACCESS_TOKEN>"Implementation Checklist
- Use the WABA ID in the subscribed_apps endpoint.
- Use an access token that can manage the WhatsApp business assets involved.
- Confirm that the callback URL is already verified before testing normal events.
- Send a controlled test event and verify it reaches your backend logs.
The full webhook setup, verification flow, event parsing, and troubleshooting are covered in How to Set Up WhatsApp Webhooks.
Step 10
Test Incoming Messages & Status Events
After the webhook is verified and the app is subscribed to the WABA, test both directions of the integration. Send a message from a customer phone to the business number and confirm your backend receives the incoming message event. Then send an outbound API message and confirm later webhook events reference the same WhatsApp message ID returned by the send request.
Do not treat the initial API response as final delivery. The send request gives you a message ID, while sent, delivered, read, or failed updates arrive asynchronously. Store those updates against the exact outbound message record so you can trace the complete lifecycle.
Test Both Event Types
- Send a customer message to the business number and confirm the incoming message reaches your webhook.
- Send an outbound API message and save the returned WhatsApp message ID.
- Match later status events to that message ID instead of matching only by phone number.
- Keep webhook processing idempotent so duplicate deliveries do not create duplicate business actions.
For webhook payload handling, continue with How to Set Up WhatsApp Webhooks. For a deeper explanation of sent, delivered, read, and failed states, use WhatsApp Cloud API Message Statuses Explained.
Step 11
Production Setup Checklist
Before connecting the Cloud API to real customer workflows, verify the production pieces together. The goal is to remove temporary development assumptions, protect credentials, confirm event delivery, and make failures traceable before the integration starts sending important business messages.
Production Checklist
- The correct business phone number is verified, registered, and attached to the intended WABA.
- The production token is server side, protected, and tied to the right app, business, system user, permissions, and assets.
- Phone Number ID and WABA ID are stored separately and verified against the production business assets.
- The webhook callback uses HTTPS, verification succeeds, and the app is subscribed to the correct WABA.
- Outbound message IDs and incoming webhook event identifiers are stored for correlation and deduplication.
- Template names, languages, and dynamic data mappings are tested for every production workflow that uses templates.
- Logs redact tokens and unnecessary personal data but keep safe IDs, status codes, and provider errors needed for debugging.
- Retries are limited to safe cases and important workflows use idempotency so the same event cannot create duplicate messages or records.
Step 12
Common WhatsApp Cloud API Setup Problems
Most setup failures come from one of a few layers: the wrong business asset, an incorrect ID, token permissions, phone registration, webhook verification, or a message payload that does not match the current messaging context. Check the exact failing layer before changing unrelated settings.
The API Says the Object Does Not Exist
Confirm whether the endpoint expects the WABA ID or Phone Number ID, then verify that the token has access to the same business assets.
The Phone Number Is Verified but Cannot Send
Check the phone registration state, two step verification setup, Phone Number ID, and whether you are testing with the correct production or development number.
The Access Token Works in One Place but Fails in the App
Make sure the server is loading the intended environment variable, the token has not expired, and the system user or account that created it has the required permissions and WhatsApp assets.
Webhook Verification Fails
Confirm the callback is public over HTTPS, the verify token matches exactly, and the GET verification route returns the challenge value with a successful response.
Messages Are Accepted but You Do Not See Delivery Updates
Store the outbound message ID, confirm the app is subscribed to the correct WABA and webhook fields, and inspect backend logs for the corresponding status event.
For a systematic debugging process, continue with How to Debug a WhatsApp Cloud API Integration.
Related Guides
Continue Learning
Need Implementation Help?
Need Help With Your WhatsApp or Automation Project?
If you need help building, integrating, troubleshooting, or improving a production system, you can discuss the project with me directly.