WhatsApp Business API Documentation: A Developer's Guide & Resource Index (2026)

TL;DR — Quick Links

The five references you will use most:

Where Meta's Official Documentation Lives

Meta organises the WhatsApp Business Platform docs into four areas you will return to repeatedly.

Authentication

All Cloud API calls are authenticated with a System User Access Token generated in Meta Business Suite.

The recommended production pattern is a System User (not a personal user account) scoped to whatsapp_business_messaging and whatsapp_business_management permissions. Tokens can be set to never expire, which avoids the operational burden of 60-day user token rotation.

The access token is passed as a Bearer token in the Authorization header on every request. Meta's full authentication setup guide: Access Tokens — WhatsApp Business Platform.

Sending Messages

Messages are sent via a POST to the Graph API at the path /PHONE_NUMBER_ID/messages. The PHONE_NUMBER_ID is the identifier for the WhatsApp-enabled phone number in your Business Account, not the number itself.

Request shape (schematic):

POST https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/messages
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "{RECIPIENT_PHONE_E164}",
  "type": "text",
  "text": {
    "body": "Your message body here."
  }
}

For template messages, replace "type": "text" with "type": "template" and provide a template object that names the approved template and supplies any variable values.

For media messages (image, document, video, audio), set the appropriate type and provide either a media_id (from a prior media upload) or a publicly accessible URL. Meta's full send-message reference: Send Messages.

Receiving Messages (Webhooks)

The Cloud API delivers inbound messages and status updates to your server via webhooks — there is no polling endpoint.

Setup steps:

1. Register a publicly accessible HTTPS endpoint in your Meta App dashboard.
2. Respond to Meta's verification GET request with the hub.challenge value.
3. Verify each incoming POST using the X-Hub-Signature-256 header (HMAC-SHA256 of the raw request body, keyed with your App Secret).
4. Return HTTP 200 within five seconds of receiving a webhook event; process asynchronously if your handler is slow.

Payload orientation: Each webhook delivery wraps one or more entry objects. Inside, changes[].value contains the event data. For inbound messages, messages[] holds the message object. For delivery and read receipts, look at statuses[]. Full reference: Webhooks.

Message Templates

Templates are pre-approved message structures required for any business-initiated message sent outside an open 24-hour service window.

Categories:

• • Marketing — Promotions, offers, product announcements. Highest per-conversation rate.
• • Utility — Transactional messages tied to an existing customer action: order confirmations, shipping updates, appointment reminders.
• • Authentication — One-time passcodes. Strictest content rules; no custom footers or marketing copy.

Submission and approval: Templates are created in Meta Business Suite (or via the Business Management API) and reviewed by Meta, typically within 24 hours. Approval is not guaranteed.

Variables use positional placeholders — {{1}}, {{2}} — that are filled at send time. Full templates guide: Message Templates.

Conversation Categories and Pricing

WhatsApp bills per conversation, not per message. A conversation is a 24-hour window opened by the first message in an exchange. Category determines the rate.

Rates vary by country. The per-country rate card is in Meta's pricing reference: Conversation Pricing.

Practical note: If a user messages you and you reply within the 24-hour window, that is a Service conversation — even if you send a template. Category is determined at the point the conversation window opens, not by message type.

Messaging Tier Limits

The API enforces limits on how many unique users you can message in a rolling 24-hour period. Tier progression is based on volume and phone number quality rating.

New phone numbers start at Tier 1. Progression to higher tiers happens automatically when you consistently send high-quality messages at or near your current limit. Meta's tier documentation: Messaging Limits.

Rate Limits

Beyond conversation-level tier limits, the Graph API enforces HTTP-level rate limits per access token.

Best practices:

• • Implement exponential backoff with jitter when you receive 429 or error code 130429 responses
• • Queue outbound messages and send at a controlled rate rather than bursting
• • For high-volume sends (campaigns, notifications), spread sends across time rather than firing all at once
• • Monitor your error rate in Meta Business Suite's API health dashboard

Meta's rate limit reference: Rate Limits & Error Codes.

Hyperleap's REST API and Webhooks

Hyperleap is a Meta-authorised Business Solution Provider (BSP) and operates on the Cloud API. If you are building on top of Hyperleap rather than calling Meta's API directly, you interact with Hyperleap's own REST API and webhook system — which expose conversation data, lead records, and message events from your Hyperleap-managed WhatsApp number.

Hyperleap's API gives you programmatic access to conversation threads, contact details, lead pipeline stages, and CRM-level data. Webhooks fire on lead creation, new inbound messages, outbound replies, and conversation start events. Book a demo to walk through the integration options with the team, or see the integration patterns.

Common Operations — Quick Reference

Common Gotchas

Meta's API Directly vs. a BSP — Which Should You Use?

Both are valid. The choice depends on what layer you want to own.

Calling Meta's Cloud API directly gives you full control, no middleware, and the lowest-cost path if you are building a custom integration. You handle webhook infrastructure, conversation management, contact records, and the UI layer yourself.

Using a BSP like Hyperleap adds a managed layer on top of the Cloud API: shared inbox, AI-powered response automation, lead management, multi-channel support (Website, WhatsApp, Instagram DM, Facebook Messenger), and your own REST API for accessing conversation data without managing the Meta API surface directly.

For a detailed breakdown: Cloud API direct vs. BSP — comparison.

Frequently Asked Questions