WhatsApp Cloud API cheat sheet

Webhook setup

• GET with hub.mode=subscribe, hub.verify_token, hub.challenge: echo the challenge if the token matches
• POST deliveries carry X-Hub-Signature-256 = sha256=HMAC(app secret, raw body)
• Subscribe the app to the messages field of the WhatsApp Business Account
• Return 200 quickly; failed deliveries are retried

Message types

• text (body up to 4096 characters)
• image, video, audio, document, sticker by link or media id
• interactive: button (3 max), list (10 rows), cta_url, flow
• template approved in WhatsApp Manager
• location, contacts, reaction

Message builder

The 24 hour window

• A user message opens a 24 hour customer service window for free-form replies
• Outside it you can only send approved templates
• Template categories: marketing, utility, authentication; pricing differs by category and country
• Get opt-in before messaging people first

Incoming payload

entry[].changes[].value
  .messages[]   from, id, timestamp, type,
                text.body | interactive.button_reply
                | interactive.list_reply
  .statuses[]   id, status: sent | delivered
                | read | failed, errors[]
  .contacts[]   profile.name, wa_id

Useful calls

• Mark as read: POST /messages with "status": "read" and "message_id"
• Upload media: POST /<PHONE_NUMBER_ID>/media, then send by id
• Download media: GET /<MEDIA_ID> returns a short-lived URL that also needs the token

Common errors

• 131047 re-engagement: outside the 24 hour window, use a template
• 131026 message undeliverable
• 132001 template does not exist in that language
• 190 access token expired or invalid
• 130429 throughput limit reached