WhatsApp Cloud API

When to Use

• 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)

Quick Reference

https://graph.facebook.com/v21.0

POST /{phone-number-id}/messages

POST /{phone-number-id}/media

Authorization: Bearer {access-token}

"messaging_product": "whatsapp"

+{country}{number}

+18091234567

Core API — Send Message

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

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

Message Types

type

text

image

video

audio

document

sticker

location

contacts

reaction

interactive

template

Webhooks

{
  "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"
    }]
  }]
}

sent

delivered

read

failed

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)

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

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
• Media — Upload, download, formats
• Interactive — Buttons, lists, products
• Phone Numbers — E.164, IDs, verification
• Error Codes — Common errors and retries