Skip to main content
Every WhatsApp Cloud API call is an HTTP POST request with four parts: an endpoint URL, authorization headers, a JSON body, and a JSON response. Understanding these four parts is the foundation for reading any API example or debugging any failure.

​
Part 1 — Endpoint (the URL)

POST https://graph.facebook.com/v21.0/1158939770629471/messages
SegmentExampleMeaning
Base URLgraph.facebook.comMeta’s Graph API server — all Meta APIs live here
Versionv21.0The API version in use
Phone Number ID1158939770629471Which WhatsApp number sends the message
ActionmessagesWhat to do — post a new message
The HTTP method is always POST when sending a message.

​
Part 2 — Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
  • Authorization — proves who you are. Uses your system-user token or temporary token.
  • Content-Type — tells Meta the body is JSON.
Both are required on every request. Missing Authorization returns a 401 error. Think of headers like showing your ID card at a building entrance before the guard lets you in.

​
Part 3 — Body (JSON)

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "919876543210",
  "type": "text",
  "text": {
    "body": "Hello!"
  }
}
FieldRequiredMeaning
messaging_productyesAlways "whatsapp"
recipient_typenoAlmost always "individual"
toyesRecipient phone number, digits only, with country code, no +
typeyesMessage type: text, image, template, etc.
type-specific fieldsyese.g. text.body for text, template.name for templates

​
Part 4 — Response

On success, Meta returns HTTP 200 with: 
{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "919876543210", "wa_id": "919876543210" }],
  "messages": [{ "id": "wamid.HBgM..." }]
}
messages[0].id is the WhatsApp message ID (wamid) — save it if you need to track delivery status via status webhooks later.

​
API versioning

The v21.0 in the URL is the API version. Meta releases new versions several times a year.
  • Each version is supported for approximately 2 years after release.
  • When a version is deprecated, API calls using it stop working and return an error.
  • Upgrading is one line of code: change v21.0 to the new version in your base URL.
  • Check the current versions at developers.facebook.com/docs/graph-api/changelog.
Think of it like Android versions — new releases bring new features, and old ones eventually stop receiving support.

​
Frequently asked

It is the API version. Meta releases new versions regularly and deprecates old ones after about 2 years. If you use a deprecated version your calls will stop working — keep your code on a supported version.
Two headers are required: Authorization: Bearer YOUR_TOKEN (your access token) and Content-Type: application/json (tells Meta the body is JSON).
Always "whatsapp". Meta’s Graph API serves multiple products, so this field tells it which product the request belongs to.
A unique ID Meta assigns to each registered WhatsApp number. It goes in the URL to say which number should send the message. Find it in the Meta developer dashboard → API Setup. See the glossary.
Your API calls fail with an error. Update the version number in your URL (one line change) to a currently supported version.
No. The to field must be digits only with the country code, no + or spaces. For example: 919959623255 not +91 99596 23255.

​
Gotchas & common mistakes

  • Wrong method — use POST, not GET.
  • + in phone number — remove it. 919959623255 not +919959623255.
  • Outdated version — if you copy a tutorial using v16.0, upgrade to the current version or calls will fail once that version is deprecated.
  • Missing Content-Type — some HTTP clients need this set explicitly or Meta returns a body-parsing error.
  • Token in URL instead of header — the token must be in the Authorization header, not as a query parameter.