WhatsApp Cloud API Developer Guide: Webhooks, Limits, Errors and Code

Meta's documentation for the WhatsApp Business Platform is thorough, but it is spread across dozens of pages, and the numbers that matter in production — how fast you can send, what a webhook looks like, what error 131047 means — sit in different places. This guide pulls them together, checked against Meta's docs in September 2026. If you have not created your app and test number yet, start with the WhatsApp Cloud API setup guide.

WhatsApp Business API REST API documentation: where it lives

The Cloud API is not a separate service with its own SDK — it is a set of endpoints on Meta's Graph API, called over HTTPS at graph.facebook.com with a bearer token. Everything official is on Meta for Developers:

• WhatsApp Business Platform docs — guides for getting started, messages, templates, webhooks, phone numbers and limits. Older links under developers.facebook.com/docs/whatsapp redirect or still work.
• API reference — each endpoint (messages, phone numbers, WhatsApp Business Account, templates, media) with fields and sample requests.
• Graph API changelog — the current version. At the time of writing that is v26.0, released 29 July 2026. Put the version in every URL and upgrade deliberately.
• Error codes page — the full list of Cloud API error codes, summarised below.
• Webhooks reference — one page per webhook field, with sample payloads for each message and status type.

The two IDs you use most: the Phone Number ID for sending (POST /PHONE_NUMBER_ID/messages) and the WhatsApp Business Account ID for templates, phone number lists and webhook subscriptions.

Webhooks: verification first

Incoming messages and delivery updates reach you only through webhooks. When you save a callback URL in the app's WhatsApp configuration, Meta first sends a GET request to it with three query parameters:

• hub.mode — always subscribe.
• hub.verify_token — the string you typed into the Verify Token field.
• hub.challenge — a value you must send back.

Your endpoint checks that hub.verify_token matches your own secret and responds with status 200 and the hub.challenge value as the body. Anything else and Meta will not save the URL. Then subscribe the app to the messages webhook field.

After that, every event arrives as a POST with a JSON body and an X-Hub-Signature-256 header containing sha256= followed by an HMAC-SHA256 of the raw request body, keyed with your app secret. Compute the same HMAC over the raw bytes and compare before trusting the payload — parse the JSON only after the check.

WhatsApp Business API webhook payload structure

Every WhatsApp webhook has the same envelope: object is whatsapp_business_account; entry is an array whose items carry an id (the WABA ID) and a changes array; each change has a field (for example messages) and a value holding the event. Inside value for the messages field you will find:

A trimmed incoming text message, as in Meta's reference:

{"object":"whatsapp_business_account","entry":[{"id":"WABA_ID","changes":[{"field":"messages","value":{"messaging_product":"whatsapp","metadata":{"display_phone_number":"15550783881","phone_number_id":"PHONE_NUMBER_ID"},"contacts":[{"profile":{"name":"Sheena Nelson"},"wa_id":"16505551234"}],"messages":[{"from":"16505551234","id":"wamid.HBgL...","timestamp":"1749416383","type":"text","text":{"body":"Does it come in another color?"}}]}}]}]}

A status update uses the same envelope, with statuses in place of contacts and messages:

"statuses":[{"id":"wamid.HBgL...","status":"delivered","timestamp":"1750263773","recipient_id":"16505551234","pricing":{"billable":true,"category":"service"}}]

Status values move through sent, delivered and read, or end at failed. They can arrive out of order, and one POST can batch several entries or changes — loop over every level rather than reading index 0.

WhatsApp Business API webhook integration example

A minimal Node.js (Express) handler, with the verify token and app secret in environment variables:

1. app.get("/webhook", (req, res) => { const ok = req.query["hub.mode"] === "subscribe" && req.query["hub.verify_token"] === process.env.VERIFY_TOKEN; ok ? res.status(200).send(req.query["hub.challenge"]) : res.sendStatus(403); });
2. app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => { const sig = "sha256=" + crypto.createHmac("sha256", process.env.APP_SECRET).update(req.body).digest("hex"); if (sig !== req.get("x-hub-signature-256")) return res.sendStatus(401); res.sendStatus(200); handle(JSON.parse(req.body)); });

• Answer 200 fast, work later. Acknowledge the POST, then push the payload to a queue or background job. If Meta does not get a 200, it retries with decreasing frequency for up to 7 days.
• Deduplicate on the wamid. Retries mean the same message can arrive twice.
• Expect big bodies. WhatsApp webhook payloads can be up to 3 MB. Media arrives as an ID you download separately, not as bytes in the webhook.
• Use a timing-safe comparison for the signature in production (crypto.timingSafeEqual in Node).

WhatsApp Business API rate limits explained

“Rate limit” means four different things on the Cloud API. Mixing them up is why teams raise their throughput and still get errors.

The automatic throughput upgrade to 1,000 mps requires an unlimited messaging limit, messaging 100,000 or more unique users outside the customer-service window in a moving 24 hours, and a quality rating of yellow or better. The upgrade can take up to a minute, during which sends return 131057.

WhatsApp Business API error codes list

Errors come back in the API response as an error object with a code, and for asynchronous failures in the errors array of a failed status webhook. The codes you will meet most often, from Meta's error codes page:

Log the full error object, not just the code — the message and any details alongside it usually say which parameter or rule failed. Meta's error codes page lists every code, including the registration and two-step verification errors (the 133xxx range) you meet when adding numbers.

Sending messages from your code

Every send is the same request: POST to https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages with a bearer token and a JSON body containing messaging_product whatsapp, the recipient in to (international format, no plus sign), a type, and an object for that type.

WhatsApp Business API Node.js integration example

Node.js 18 and later ship fetch, so no library is needed. Sending an approved template:

1. const url = "https://graph.facebook.com/v26.0/" + process.env.PHONE_NUMBER_ID + "/messages";
2. const res = await fetch(url, { method: "POST", headers: { Authorization: "Bearer " + process.env.WA_TOKEN, "Content-Type": "application/json" },
3. body: JSON.stringify({ messaging_product: "whatsapp", to: "91XXXXXXXXXX", type: "template", template: { name: "order_update", language: { code: "en" }, components: [{ type: "body", parameters: [{ type: "text", text: "A1042" }] }] } }) });
4. const data = await res.json(); if (!res.ok) throw new Error(data.error.code + ": " + data.error.message);
5. console.log(data.messages[0].id); // wamid — match it to status webhooks

For a free-form reply inside the 24-hour window, change the body to type text with text: { body: "Your order ships today" }.

WhatsApp Business API PHP SDK example (cURL)

Meta does not publish a PHP SDK for the WhatsApp Cloud API. PHP's built-in cURL extension is all you need to call the REST API — here, a text reply:

1. $payload = json_encode(["messaging_product" => "whatsapp", "to" => "91XXXXXXXXXX", "type" => "text", "text" => ["body" => "Your order ships today"]]);
2. $ch = curl_init("https://graph.facebook.com/v26.0/" . getenv("PHONE_NUMBER_ID") . "/messages");
3. curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_POSTFIELDS => $payload,
4. CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("WA_TOKEN"), "Content-Type: application/json"]]);
5. $result = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch);
6. if ($status !== 200) { error_log($result["error"]["code"] . ": " . $result["error"]["message"]); }

Third-party PHP packages for the Cloud API are available on Packagist and GitHub. They are not maintained by Meta, so check that a package tracks recent Graph API versions before you depend on it.

A production checklist

• Use a system user token stored as a server secret, never a temporary token.
• Pin the Graph API version in one config value and plan upgrades from the changelog.
• Verify signatures on every webhook and acknowledge within your handler before heavy work.
• Queue outbound sends and respect throughput (130429) and pair rate (131056) with backoff.
• Store wamid → your record so status webhooks update the right message.
• Handle 131047 by switching to a template, and 131050 by marking the contact opted out.
• Watch template quality — a paused template (132015) will fail every send until fixed.

Building this versus using a panel

Everything above is what it takes to send and receive reliably. A team inbox, agent assignment, template management for non-developers, broadcasts and a chatbot are further projects on top. If WhatsApp is a feature inside your own product, build on the Cloud API directly.

If your goal is simply for your team to work on WhatsApp, wbm.link gives you that as a no-code panel on the WhatsApp Business Platform — shared inbox, template builder that submits to Meta, broadcasts to labels or CSV contacts, keyword auto-replies, a flow chatbot and an AI assistant — for ₹999 per connected number per month with unlimited team members. It has no public API or customer webhooks, so it is not a replacement for a custom integration; it is the choice when you do not want to write one.