WhatsApp Cloud API: Get Started
Get up and running with the WhatsApp Cloud API: register as a developer, create a Meta app, send your first message and set up a test webhook. Along the way you'll generate a secure access token and send both template and non-template messages.
Heads up: this guide is for developers building on the WhatsApp Business Platform. If you're having trouble with your personal WhatsApp account, visit the WhatsApp Help Center.
Download the sample app
The Jasper's Market sample app includes every message and code snippet from Meta's Jasper's Market demo. Use it to learn how an app sends and handles WhatsApp Cloud API data.
Open-source example on GitHub
Prerequisites
- A Facebook account or a managed Meta account
- Developer registration. Not registered yet? Go to the developer registration page and follow the prompts.
- A device with WhatsApp for sending and receiving test messages
1Create a new Meta app with WhatsApp
- Open the Meta App Dashboard to create a new app with the WhatsApp use case.
- Click Create App.
- Enter your app's name and your email.
- Select the Connect with customers through WhatsApp use case and click Next.
- Pick an existing business portfolio or create a new one.
- Review the publishing requirements (you may not have any yet) and click Next.
- Confirm your details, use case and business portfolio. Click Previous to change anything, or Create app to finish.
Once the app is created you land on Customize use case › Connect on WhatsApp › Quickstart in the dashboard.
2Start using the API
- Click Start using the API. This takes you to the API Setup page, where you add a phone number and send your first message.
- In API Setup, connect your app to a Messaging account so it can reach the Cloud API and send messages for your business:
- Existing account: choose it from the dropdown.
- New account: click Create a WhatsApp Business account and follow the prompts to set up your business profile.
- When connected, your Messaging account ID appears in the API Setup panel. Save it; you'll use it in API calls.
Note: if you created a new Meta Business Portfolio while creating the app, a Messaging account may have been made for you automatically. Check the connection in API Setup before you continue.
3Send and receive messages
- Click Generate access token to create a temporary token for a test message.
- Choose a From phone number in the dropdown, or add a new one.
- Enter a To phone number that will receive the test message.
- Click Send message. Keep your test phone number ID and Messaging account ID handy for later.
- When the message arrives, reply to it to keep the conversation going.
The left-side menu in the dashboard lets you customise the use case's settings and permissions. You can change these at any time:
- Permissions and featuresRequired and optional permissions, and adding them to App Review.
- QuickstartStart using the API and manage your Messaging account.
- API SetupTokens, sending and receiving, webhooks and the SDK.
- ConfigurationConfigure webhooks and the WhatsApp SDK.
- ResourcesDeveloper docs, Meta Blueprint courses and support.
- Tech Provider onboardingScale the WhatsApp Business Platform for your business.
- Partner SolutionsCreate a partner solution.
- Embedded Signup BuilderAdd the Embedded Signup flow to your site or client portal.
4Set up the test webhook app
You need a webhook endpoint to be notified about message statuses such as delivered and read. For testing, use the sample server from the Using a test webhook app guide.
Once it's running, reply in the WhatsApp chat you started with yourself. Your test app will receive a payload like this:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "215589313241560883",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15551797781",
"phone_number_id": "7794189252778687"
},
"contacts": [
{
"profile": { "name": "Jessica Laverdetman" },
"wa_id": "13557825698"
}
],
"messages": [
{
"from": "17863559966",
"id": "wamid.HBgLMTc4NjM1NTk5NjYVAGHAYWYET688aASGNTI1QzZFQjhEMDk2QQA=",
"timestamp": "1758254144",
"text": { "body": "Hi!" },
"type": "text"
}
]
},
"field": "messages"
}
]
}
]
}
5Create a system user and a permanent token
The temporary token you used to send the hello_world template expires quickly, so it isn't suitable for development. Create a permanent token for use across the WhatsApp Business Platform:
- Go to Business Settings and click System users in the sidebar.
- Click Add+ in the top-right corner and follow the prompts to create a system user.
- Select the new system user and click Assign Assets:
- Select your app and turn on Manage app under Full control.
- Select your WhatsApp account and turn on Manage WhatsApp Business accounts under Full control.
- Click Assign assets.
- Click Generate token, follow the prompts, and add these permissions:
- Copy the token and store it somewhere safe. You'll need it in the next step.
Treat this token like a password. Keep it in an environment variable or secrets manager, never in front-end code or a public repository.
6Send a non-template message
Replying to your earlier test message opened a customer service window. For 24 hours you can send non-template messages to that user, so you can now message yourself freely.
Fill in your test phone number ID, system user token and your own phone number, then run this in your terminal:
curl 'https://graph.facebook.com/v23.0/<TEST_BUSINESS_PHONE_NUMBER_ID>/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <SYSTEM_USER_ACCESS_TOKEN>' \
-d '
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "<WHATSAPP_USER_PHONE_NUMBER>",
"type": "text",
"text": {
"body": "Hello!"
}
}'
After it sends, check your test webhook app for the event confirming the message was received.
Don't have the user's phone number? You can send to their business-scoped user ID (BSUID) by replacing to with recipient. See Send to a BSUID.
7Finish
Sending messages and receiving webhooks are the core building blocks of any WhatsApp integration. The Cloud API also supports more advanced features such as creating and managing groups, and calling. Explore them in the links below.
Learn more
- Non-template messagesText, media, location, interactive and more.
- Template messagesCreate and send approved templates.
- Groups APICreate and manage WhatsApp groups via API.
- CallingSend and receive WhatsApp calls via API.
- Business phone numbersAdd a business phone number.
- Your own webhook serverSet up a production webhook endpoint.
- Onboard Business app usersConnect existing WhatsApp Business app numbers via Embedded Signup.
- Become a partnerSolution provider programme overview.
- OpenAPI specificationThe WhatsApp API spec on GitHub.