whatsapp-cloud-api

WhatsApp Cloud API

When to Use

Activate this skill when:

• Building or modifying WhatsApp messaging features
• Sending messages (text, media, templates, interactive)
• Processing incoming webhooks from WhatsApp
• Working with template messages or conversation windows
• Handling phone number formatting (E.164)
• Debugging WhatsApp API errors or status updates
• Implementing message status tracking (sent, delivered, read)
• Running a number on both the WhatsApp Business App and Cloud API (Coexistence)

Quick Reference

Item	Value
Base URL	https://graph.facebook.com/v21.0
Send Message	POST /{phone-number-id}/messages
Upload Media	POST /{phone-number-id}/media
Auth	Authorization: Bearer {access-token}
Required Field	"messaging_product": "whatsapp"
Phone Format	E.164: +{country}{number} (e.g., +18091234567)
Rate Limit	80 messages/second (Cloud API)

Core API — Send Message

All messages go through a single endpoint:

POST https://graph.facebook.com/v21.0/{phone-number-id}/messages
Authorization: Bearer {access-token}
Content-Type: application/json

Response:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "+16505555555", "wa_id": "16505555555" }],
  "messages": [{ "id": "wamid.HBgL..." }]
}

Message Types

Type	type Field	Details
Text	text	Plain text, max 4096 chars, supports URL preview
Image	image	JPEG/PNG, max 5MB, optional caption
Video	video	MP4, max 16MB, optional caption
Audio	audio	AAC/MP3/OGG, max 16MB
Document	document	Any format, max 100MB, optional filename
Sticker	sticker	WebP, static 100KB / animated 500KB
Location	location	latitude, longitude, name, address
Contacts	contacts	Structured contact cards
Reaction	reaction	Emoji reaction to a message
Interactive	interactive	Buttons, lists, products
Template	template	Pre-approved message templates

For full specs and code examples, see references/MESSAGING.md.

Webhooks

Your server receives POST requests for incoming messages and status updates.

Incoming message structure:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "phone_number_id": "ID", "display_phone_number": "NUM" },
        "contacts": [{ "profile": { "name": "John" }, "wa_id": "16315551234" }],
        "messages": [{
          "from": "16315551234",
          "id": "wamid.ABC...",
          "timestamp": "1683229471",
          "type": "text",
          "text": { "body": "Hello" }
        }]
      },
      "field": "messages"
    }]
  }]
}

Status update types: sent → delivered → read | failed

For webhook verification, payload parsing, and all status types, see references/WEBHOOKS.md.

Conversation Window

• When a customer messages you, a 24-hour service window opens
• Inside the window: send any message type freely (service messages are FREE)
• Outside the window: only template messages can be sent (paid per message)
• No API endpoint to "close" a conversation — windows expire automatically
• Template messages open their own 24h window per category (marketing, utility, auth)

For full lifecycle, pricing, and category rules, see references/CONVERSATIONS.md.

Coexistence

Run one number on the WhatsApp Business App and the Cloud API simultaneously — the business keeps chatting from the app while you integrate via the API.

• Onboard via a customized Embedded Signup flow (featureType: "whatsapp_business_app_onboarding"), not standard registration
• Onboarding triggers a one-time sync of past messages (history, up to 180 days) and contacts (smb_app_state_sync)
• Messages the business sends from the app are mirrored to your webhook via smb_message_echoes
• App-sent messages are FREE; coexistence numbers are capped at 20 msg/sec
• Chat history is preserved; template messages and the 24h window still apply

For onboarding, sync, status checks, and webhook payloads, see references/COEXISTENCE.md.

Common Patterns

Send a text message

{
  "messaging_product": "whatsapp",
  "to": "+18091234567",
  "type": "text",
  "text": { "body": "Hello! How can we help you?" }
}

Send a template message

{
  "messaging_product": "whatsapp",
  "to": "+18091234567",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "en_US" }
  }
}

Mark a message as read

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid.HBgL..."
}

Error Handling

Code	Error	Action
131030	Recipient not on WhatsApp	Validate number before sending
131047	Re-engagement required	Send a template message first
131050	User stopped marketing messages	Respect opt-out, send only service/utility
131056	Pair rate limit hit	Slow down, implement backoff
130429	Rate limit exceeded	Queue messages, max 80/sec

For full error reference and retry strategies, see references/ERROR-CODES.md.

Best Practices

1. Always use E.164 phone format — +{country}{number}, no spaces or dashes
2. Verify webhooks — Respond to GET challenge with hub.challenge value
3. Return 200 immediately on webhook POST — process asynchronously
4. Store wamid IDs — Needed for replies, reactions, and read receipts
5. Use template messages to re-engage after the 24h window expires
6. Handle idempotency — Webhook may deliver the same event multiple times
7. Check wa_id vs input — The API normalizes phone numbers; wa_id is canonical
8. Rate limit awareness — 80 msg/sec for Cloud API; implement queue + backoff

References

• Messaging — All message types
• Webhooks — Setup and payloads
• Templates — Management and sending
• Conversations — Window lifecycle and pricing
• Coexistence — Business App + Cloud API on one number
• Media — Upload, download, formats
• Interactive — Buttons, lists, products
• Phone Numbers — E.164, IDs, verification
• Error Codes — Common errors and retries