Meta

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

  1. Register as a Meta developer at developers.facebook.com.
  2. In the App Dashboard choose Create app, pick the use case Connect with customers through WhatsApp, and attach a business portfolio.
  3. 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 phoneNumberId and wabaId.
  4. Add your own WhatsApp number as a test recipient there and put it in recipientPhone (with + and country code).
  5. 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_management and business_management. Paste it into accessToken. (The temporary token on API Setup works too, but expires within hours.)
  6. 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

  1. Fill in accessToken, wabaId, phoneNumberId and recipientPhone.
  2. Run 1. Account and phone number to check your setup.
  3. 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.
  4. 3. Media saves mediaId for the media-by-ID requests. 4. Templates, 5. Business profile and 6. Webhooks follow.
  5. Requests that need an incoming message's ID use incomingMessageId: copy the messages[0].id (a wamid.) 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

CodeMeaningWhat to do
190Access token expired or invalidGenerate a system user token; temporary tokens expire quickly.
10, 200, 131005Permission missing, or no access to this accountAdd whatsapp_business_* permissions and assign the account to the system user.
100, 131008, 131009Invalid, missing or wrong-format parameterCheck the body against the request; phone numbers need + and country code.
131047More than 24 hours since the user last wroteSend an approved template instead.
131026Message undeliverable (not a WhatsApp number, old app, ...)Check the number; do not retry blindly.
132000 / 132001 / 132012Template parameter count wrong / template or language not found or not approved / parameter format wrongMatch the template exactly.
133010Phone number not registeredCall Register the phone number.
130429, 131056, 80007, 4Throughput or rate limit reachedSlow down and retry later.
131042Payment problemFix billing on the Messaging account.
368, 131031Account restricted for a policy violationSee WhatsApp Manager > Account quality.

Links

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

How to test the WhatsApp Cloud API (Meta) in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the WhatsApp Cloud API (Meta) collection, without the publisher's secrets.
  3. 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.
  4. 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.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.