WhatsApp Cloud API (Meta)
Send WhatsApp text, templates, media, buttons, lists and reactions, manage media, templates and profile, and set up webhooks.
CommunicationGuided#whatsapp#messaging#cloud-api#meta#templates#webhooks
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
The WhatsApp Business Platform Cloud API lets a business send and receive WhatsApp messages from its own software, hosted by Meta: text, media, interactive buttons and lists, locations, reactions and pre-approved template messages, plus media storage, template management and the business profile. Everything is a Graph API call to https://graph.facebook.com/v27.0, authenticated with a bearer token, and incoming messages and delivery statuses reach you by webhook.
Set up, step by step
- Register as a Meta developer at developers.facebook.com.
- In the App Dashboard choose Create app, pick the use case Connect with customers through WhatsApp, and attach a business portfolio.
- Open Customize use case > API Setup. Connect a Messaging account (until 2026 called the WhatsApp Business account, WABA; the ID did not change) or create one. Meta gives you a free test phone number. Copy the phone number ID and the Messaging account ID into
phoneNumberIdandwabaId. - Add your own WhatsApp number as a test recipient there and put it in
recipientPhone(with+and country code). - Create a permanent token: Business settings > System users > Add > Assign assets (your app with Manage app, and the WhatsApp/Messaging accounts) > Generate token with
whatsapp_business_messaging,whatsapp_business_managementandbusiness_management. Paste it intoaccessToken. (The temporary token on API Setup works too, but expires within hours.) - To go live with a real number: add it in WhatsApp Manager, verify it (request_code / verify_code) and register it, add a payment method, and get business verification for higher limits.
Permissions: whatsapp_business_messaging (send messages, message webhooks), whatsapp_business_management (phone numbers, templates, profile, account webhooks). Direct developers working on their own business do not need App Review; Tech Providers serving other businesses need Advanced access through App Review, otherwise calls return error 200.
The account model in 2026
Since late 2026 the old WABA is split into a WhatsApp account (holds one phone number and its profile) and a Messaging account (templates, billing, webhook subscriptions). Endpoints, IDs and tokens are unchanged: the old WABA ID is now the Messaging account ID, so every {{wabaId}} request here works as before. If your token can bill more than one Messaging account on the same number, add messaging_account_id to send requests.
The 24-hour customer service window
When a person messages you, a 24-hour window opens (and resets with each new message). Inside it you may send any message type in this collection. Outside it, only approved templates can be sent; anything else fails with 131047. Templates are the only way to start a conversation.
How to use this collection
- Fill in
accessToken,wabaId,phoneNumberIdandrecipientPhone. - Run 1. Account and phone number to check your setup.
- Send Send a template (hello_world) first: on a test number this opens the chat. Reply from your phone to open the 24-hour window, then try the other requests in 2. Send messages.
- 3. Media saves
mediaIdfor the media-by-ID requests. 4. Templates, 5. Business profile and 6. Webhooks follow. - Requests that need an incoming message's ID use
incomingMessageId: copy themessages[0].id(awamid.) from your webhook.
Template bodies contain WhatsApp placeholders such as {{1}}. They are not collection variables: leave them as they are.
Limits and pricing
Meta charges per delivered message, by category (marketing, utility, authentication, service) and by the recipient's country; messages from users are free, and some service and entry-point messages are free. See Pricing. How many people you can message outside the window per 24 hours is set by your messaging limit; throughput is per phone number.
Common errors
| Code | Meaning | What to do |
|---|---|---|
| 190 | Access token expired or invalid | Generate a system user token; temporary tokens expire quickly. |
| 10, 200, 131005 | Permission missing, or no access to this account | Add whatsapp_business_* permissions and assign the account to the system user. |
| 100, 131008, 131009 | Invalid, missing or wrong-format parameter | Check the body against the request; phone numbers need + and country code. |
| 131047 | More than 24 hours since the user last wrote | Send an approved template instead. |
| 131026 | Message undeliverable (not a WhatsApp number, old app, ...) | Check the number; do not retry blindly. |
| 132000 / 132001 / 132012 | Template parameter count wrong / template or language not found or not approved / parameter format wrong | Match the template exactly. |
| 133010 | Phone number not registered | Call Register the phone number. |
| 130429, 131056, 80007, 4 | Throughput or rate limit reached | Slow down and retry later. |
| 131042 | Payment problem | Fix billing on the Messaging account. |
| 368, 131031 | Account restricted for a policy violation | See WhatsApp Manager > Account quality. |
Links
- Cloud API overview and Get started
- Send messages, Templates, Media
- Webhooks, Error codes
- Access tokens, Permissions, Graph API changelog
- Official OpenAPI spec: github.com/meta/openapi
Endpoints 30
1. Account and phone number
- GETList phone numbers
/{{wabaId}}/phone_numbers?fields=id,display_phone_number,verified_name,quality_rating,code_verification_statusLists the business phone numbers attached to your Messaging account (WABA): display number, verified business name, phone number ID and quality rating (GREEN,… - GETPhone number details
/{{phoneNumberId}}?fields=id,display_phone_number,verified_name,quality_rating,code_verification_statusReads one business phone number: its display number, verified name, quality rating and whether ownership has been verified (code_verification_status). Use it… - POSTRequest a verification code
/{{phoneNumberId}}/request_codeFirst step of proving you own a newly added number: WhatsApp sends a one-time code to that number. code_method is SMS or VOICE; language is the locale of the… - POSTVerify the code
/{{phoneNumberId}}/verify_codeSecond step of number verification: send the code that arrived by SMS or voice call (put it in verificationCode). On success the number's… - POSTRegister the phone number
/{{phoneNumberId}}/registerRegisters a verified number for use with Cloud API. Registration can only be done through the API, not in WhatsApp Manager. Body: messaging_product = whatsapp…
2. Send messages
- POSTSend a template (hello_world)
/{{phoneNumberId}}/messagesSends Meta's sample template hello_world (language en_US, no variables), which every new Messaging account has. Templates are the only messages you may send… - POSTSend a template with variables
/{{phoneNumberId}}/messagesSends an approved template and fills its placeholders. Each components entry targets a part of the template (header, body, button) and lists its parameters in… - POSTSend a text message
/{{phoneNumberId}}/messagesSends plain text inside the 24-hour window. text.body holds the message (URLs are clickable); set preview_url to true to show a link preview of the first URL.… - POSTSend an image by link
/{{phoneNumberId}}/messagesSends an image fetched from a public HTTPS URL, with an optional caption (max 1024 characters). Supported: JPEG, PNG and static WebP up to 5 MB. Cloud API… - POSTSend an image by media ID
/{{phoneNumberId}}/messagesSends an image you uploaded earlier with 3. Media / Upload media: use image.id instead of link. Uploaded media IDs stay valid for 30 days, are faster than… - POSTSend a document by link
/{{phoneNumberId}}/messagesSends a file the user can download, here a PDF from a URL. filename (with extension) sets the name and icon the user sees; caption is optional. To send an… - POSTSend reply buttons
/{{phoneNumberId}}/messagesAn interactive message with up to three quick-reply buttons. Each button needs a unique reply.id (max 256 characters, comes back in the webhook) and a… - POSTSend a list message
/{{phoneNumberId}}/messagesAn interactive list: one button (action.button, max 20 characters) opens a menu of up to 10 rows grouped into sections. Each row needs an id and a title (max… - POSTSend a location
/{{phoneNumberId}}/messagesSends a map pin. latitude and longitude (decimal degrees) are required; name and address are optional labels shown on the pin. To ask the user for *their*… - POSTReply to a message (quote it)
/{{phoneNumberId}}/messagesAny message type can be sent as a contextual reply: add context.message_id with the wamid of the user's message (incomingMessageId) and WhatsApp shows the… - POSTReact to a message
/{{phoneNumberId}}/messagesPuts an emoji reaction on a message the user sent you: reaction.message_id is its wamid (incomingMessageId), reaction.emoji the emoji (or its escape… - POSTMark a message as read
/{{phoneNumberId}}/messagesShows the blue double ticks on a user's message: send status: "read" with the message_id (wamid) from the incoming-message webhook. Earlier messages in the… - POSTShow a typing indicator
/{{phoneNumberId}}/messagesMarks the message as read and shows "typing..." to the user while you prepare an answer: the same body as Mark a message as read plus typing_indicator:…
3. Media
- POSTUpload media
/{{phoneNumberId}}/mediaUploads a file (image, document, audio, video, sticker) to Meta and returns a media id you can send with image.id, document.id, etc. Send multipart/form-data… - GETGet a media URL
/{{mediaId}}?phone_number_id={{phoneNumberId}}Turns a media ID (from an upload, or from an incoming image/document/audio webhook) into a temporary download URL plus mime_type, sha256 and file_size. The… - GETDownload media
{{mediaDownloadUrl}}Downloads the file itself from the URL returned by Get a media URL. It needs the same Authorization: Bearer token (sent by this collection). The response is… - DELETEDelete media
/{{mediaId}}?phone_number_id={{phoneNumberId}}Deletes an uploaded media file from Meta's servers before its 30 days are up, for example after the message is sent. Optional phone_number_id restricts the…
4. Templates
- GETList templates
/{{wabaId}}/message_templates?fields=id,name,status,category,language,components&limit=20Lists the Messaging account's templates with their status (APPROVED, PENDING, REJECTED, PAUSED, DISABLED, ...), category, language and components. Choose… - POSTCreate a template
/{{wabaId}}/message_templatesCreates a template and submits it for review (usually minutes, up to 24 hours). The body has: The {{1}}-style placeholders in the body are WhatsApp's, not… - GETCheck a template's status
/{{templateId}}?fields=name,status,category,rejected_reasonReads one template by ID, here only its review status (and rejected_reason if review failed). Poll it after Create a template, or rely on the…
5. Business profile
- GETGet the business profile
/{{phoneNumberId}}/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,verticalReads the profile of a business phone number: about, address, description, email, websites, vertical (industry) and profile_picture_url. Ask for fields… - POSTUpdate the business profile
/{{phoneNumberId}}/whatsapp_business_profileChanges profile fields. messaging_product is required; send only the fields you want to change. websites is a list of URLs; vertical takes an industry value…
6. Webhooks
- POSTSubscribe your app to the Messaging account
/{{wabaId}}/subscribed_appsConnects your app to the Messaging account (WABA) so its webhooks (messages, statuses, template updates) are sent to your app's callback URL. Without this,… - GETList subscribed apps
/{{wabaId}}/subscribed_appsShows which apps receive webhooks for this Messaging account. Use it to confirm the subscription; DELETE on the same path unsubscribes your app. Permission:… - GETTest your webhook verification handshake
{{webhookUrl}}?hub.mode=subscribe&hub.challenge=1158201444&hub.verify_token={{verifyToken}}Imitates the GET request Meta sends when you save your callback URL, so you can test your own endpoint first. It calls webhookUrl with hub.mode=subscribe,…
API details
- Base URL
https://graph.facebook.com/v27.0- Authentication
- A bearer token in the Authorization header
- Operations
- 30 operations on 30 pathsPOST 20GET 9DELETE 1
- Main resources
- 1. Account and phone number 52. Send messages 133. Media 44. Templates 35. Business profile 26. Webhooks 3
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-17 - Links
- Documentation
How to test the WhatsApp Cloud API (Meta) in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the WhatsApp Cloud API (Meta) collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “List phone numbers” (GET /{{wabaId}}/phone_numbers?fields=id,display_phone_number,verified_name,quality_rating,code_verification_status), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the WhatsApp Cloud API (Meta)?
Send WhatsApp text, templates, media, buttons, lists and reactions, manage media, templates and profile, and set up webhooks. It is listed under Communication and has 30 endpoints.
Who publishes the WhatsApp Cloud API (Meta)?
It is listed from Meta's public API description (an OpenAPI document), not published by Meta on Swastik Codes. Anyone who controls facebook.com can claim the profile by adding a DNS TXT record.
What is the base URL of the WhatsApp Cloud API (Meta)?
Requests go to https://graph.facebook.com/v27.0. Endpoint paths are added to this base URL.
How do I authenticate with the WhatsApp Cloud API (Meta)?
With A bearer token in the Authorization header.
How many endpoints does the WhatsApp Cloud API (Meta) have?
30 operations on 30 paths (20 POST, 9 GET, 1 DELETE). The largest groups are 1. Account and phone number, 2. Send messages, 3. Media, 4. Templates.
Is forking the WhatsApp Cloud API (Meta) free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.