Request Anatomy & API Versioning

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

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!"
  }
}

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#

Gotchas & common mistakes#