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
- Create a WhatsApp Business Account (WABA) and a phone number in your Meta Business account.
- Under Business Settings → System users, generate a permanent system user token
(with the
whatsapp_business_messagingandwhatsapp_business_managementpermissions). - 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_secretis rejected (400). A channel saved without an app secret before this rule is not deleted; the Validate action marks itinvalidwith theWHATSAPP_APP_SECRET_MISSINGerror 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_instarts aspending; campaigns are not sent to it (no_opt_insuppression). - A contact who has only written to you (created by an inbound message) is also
pending. When consent is given later, it becomessubscribed. - A keyword with an
opt_inaction and the compliance keywords BAŞLA/START also record consent (sourcekeyword); 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 return422 HS_CONTENT_INVALID(details.code = WHATSAPP_TEMPLATE_NOT_APPROVED); if the number of body variables ({{1}},{{2}}…) does not matchbody_params,WHATSAPP_TEMPLATE_PARAMS(expected). When publishing a journey, the same problems are reported as acontent_invalidissue 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);contentsbecomes the caption. - Interactive: reply buttons or a list with
whatsapp_interactive; the body text is thecontentsfield (up to 1024 characters). Meta's limits are validated in the API:
| Type | Limit |
|---|---|
button | 1–3 buttons; button title ≤ 20, ID ≤ 256 characters; titles and IDs must be unique |
list | List button text ≤ 20; 1–10 rows in total; row title ≤ 24, description ≤ 72, ID ≤ 200; with multiple sections, a section title is required (≤ 24) |
| Common | header 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=truedownloads 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 returnMEDIA_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 returns422 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.
Two-way SMS and keywords
Messages arriving from SMS, WhatsApp and RCS are written to per-contact conversations in the Inbox; keywords defined at org or app level respond to incoming messages with automatic actions (tag, journey trigger, auto-reply,…
RCS: Google RBM and Twilio RCS, rich cards and SMS fallback
The RCS (Rich Communication Services) channel sends rich cards, images and suggestion chips to the Android messaging app. Devices that do not support RCS receive the text equivalent of the same message through the app's SMS channel (ADR-0029 §3).…