PushizoDocs
Channels

WhatsApp (Meta Cloud API): setup, templates, session window and inbox

Pushizo sends WhatsApp messages directly through Meta's Cloud API; no BSP or extra hosting is needed (ADR-0029). The channel requires SMS as a plan feature. For development and testing without an external account, the mock…

Pushizo sends WhatsApp messages directly through Meta's Cloud API; no BSP or extra hosting is needed (docs/adr/0029-whatsapp-rcs-iki-yonlu-sms-eposta-isindirma.md). The channel requires SMS as a plan feature. For development and testing without an external account, the mock provider runs the same flow (template sync, inbound webhook, inbox) end to end.

1. Preparation on the Meta side

  1. Create a WhatsApp Business Account (WABA) and a phone number in your Meta Business account.
  2. Under Business Settings → System users, generate a permanent system user token (with the whatsapp_business_messaging and whatsapp_business_management permissions).
  3. Note your app's App Secret (App Settings → Basic; 32-character hexadecimal). The inbound webhook signature (X-Hub-Signature-256) is verified with this key; it is required for a real channel.

2. Connecting the channel

From the App → Channels → WhatsApp card in the dashboard, or via the API:

PUT /internal/v1/apps/{appId}/channels/whatsapp
{
  "provider": "meta_whatsapp",
  "waba_id": "102030405",
  "phone_number_id": "1098765432",
  "graph_api_version": "v23.0",
  "access_token": "EAAG…",
  "app_secret": "0123456789abcdef0123456789abcdef"
}
  • The token and app secret are stored with envelope encryption and never returned in responses (has_secret: true). If you leave the secret fields empty when updating, the existing values are kept.
  • A new registration without app_secret is rejected (400). A channel saved without an app secret before this rule is not deleted; the Validate action marks it invalid with the WHATSAPP_APP_SECRET_MISSING error and it is closed to sending — save the channel again with the app secret.
  • Post-registration validation reads the phone number (display number, verified name, quality rating).

Webhook: Enter the Webhook URL (/hooks/whatsapp/meta_whatsapp/{token}) and verify token values from the channel card in Meta App Dashboard → WhatsApp → Configuration → Webhook, and subscribe to the messages field. Meta's GET handshake is answered with hub.challenge if the token matches. If the URL leaks, generate a new token with Regenerate; the old URL becomes invalid immediately.

3. Explicit consent (opt-in) is mandatory

No message is sent to a WhatsApp subscription without a consent record:

POST /v1/apps/{appId}/users
{ "identity": { "external_id": "elif-1" },
  "subscriptions": [{ "channel": "whatsapp", "token": "+905321234567", "opt_in": { "source": "web_form" } }] }
  • A new WhatsApp subscription without opt_in starts as pending; campaigns are not sent to it (no_opt_in suppression).
  • A contact who has only written to you (created by an inbound message) is also pending. When consent is given later, it becomes subscribed.
  • A keyword with an opt_in action and the compliance keywords BAŞLA/START also record consent (source keyword); see Two-way SMS and keywords.

4. Templates and the 24-hour session window

Meta's rule: within 24 hours of the contact's last inbound message, you can send free-form text, media and interactive messages; outside the window, only approved templates can be sent.

  • Sync: Templates are read from Meta hourly, and immediately via Inbox → WhatsApp templates → Sync (POST /v1/apps/{appId}/whatsapp/templates/sync). Statuses: APPROVED, PENDING, REJECTED…
  • Send-path validation: Notifications (POST /v1/notifications), campaign sends/scheduling and inbox replies with an unapproved template return 422 HS_CONTENT_INVALID (details.code = WHATSAPP_TEMPLATE_NOT_APPROVED); if the number of body variables ({{1}}, {{2}}…) does not match body_params, WHATSAPP_TEMPLATE_PARAMS (expected). When publishing a journey, the same problems are reported as a content_invalid issue on the WhatsApp step.
  • The channel must be explicit: For notifications and campaigns with WhatsApp-only content (template/media), channels: ["whatsapp"] is required in the target; otherwise 422 (so push subscribers don't receive a message without text).
{
  "app_id": "app_…",
  "whatsapp_template": { "name": "siparis_durumu", "language": "tr", "body_params": ["{{ user.tags.order }}"] },
  "target": { "included_segments": ["seg_…"], "channels": ["whatsapp"] }
}

Template parameters are personalized with Liquid; an empty parameter or a value over 1024 characters is rejected at send time. Free-form text/media/interactive deliveries to recipients outside the window are suppressed with whatsapp_window_closed.

5. Media and interactive messages (in session)

  • Media: whatsapp_media (image, video, document, audio; https only); contents becomes the caption.
  • Interactive: reply buttons or a list with whatsapp_interactive; the body text is the contents field (up to 1024 characters). Meta's limits are validated in the API:
TypeLimit
button1–3 buttons; button title ≤ 20, ID ≤ 256 characters; titles and IDs must be unique
listList button text ≤ 20; 1–10 rows in total; row title ≤ 24, description ≤ 72, ID ≤ 200; with multiple sections, a section title is required (≤ 24)
Commonheader and footer ≤ 60 characters (Liquid supported)
{
  "contents": { "tr": "Teslimat saatini seçin" },
  "whatsapp_interactive": {
    "type": "button",
    "header": "Sipariş {{ user.tags.order }}",
    "buttons": [{ "id": "sabah", "title": "Sabah" }, { "id": "aksam", "title": "Akşam" }]
  },
  "target": { "include_aliases": { "external_id": ["elif-1"] }, "channels": ["whatsapp"] }
}

The button/row the contact selects lands in the inbox as a reply; the selected id is in the message's content.payload field. In the dashboard, these are composed in the Session message mode of the message/template/journey editor and on the Interactive tab of the inbox reply.

6. Inbox

  • Inbound messages (text, button/list reply, media, location, reaction) appear in the Inbox as per-contact conversations; the header shows the consent status and the window's end time.
  • Inbound media: Images are previewed in the conversation, and all types can be fetched via a download link. The file is streamed from Meta through an authorized proxy using the channel's token (GET /internal/v1/apps/{appId}/conversations/{id}/messages/{messageId}/media; ?download=true downloads it as an attachment). The download URL is accepted only from Meta media domains (lookaside.fbsbx.com, *.fbcdn.net, *.whatsapp.net); files over 16 MB return MEDIA_TOO_LARGE, and expired media returns 404.
  • Reply: While the window is open, text, template or interactive message; when closed, only an approved template (free-form text returns 422 WHATSAPP_WINDOW_CLOSED). Replying to a contact without a consent record returns 422 WHATSAPP_NO_OPT_IN.

7. Statuses and errors

Meta status notifications are applied to the delivery: delivered → delivered, read → opened, failed → failed. If the number does not use WhatsApp (131026), the subscription is invalidated; token/permission errors set the channel to invalid; rate limits are retried with Retry-After. The detailed mapping is in ADR-0029 §2.3.

8. Local development and E2E with mock

provider: "mock" (optional app_secret): template sync loads sample approved/pending/rejected templates, /hooks/whatsapp/mock/{token} accepts Meta-format webhooks (signature required if a key is set), and the inbound media proxy returns a small sample file. The mock webhook is never accepted unsigned in production.

On this page