Guides
Session Window vs Templates
Decision guide for when to use free-form POST /messages versus approved Cloud templates on POST /templates/send.
Meta customer care window
On Cloud API, free-form messages are allowed for about 24 hours after the customer’s last inbound message. Outside that window you must use an approved template.
Quick decision table
| Situation | Cloud API | Device / QR |
|---|---|---|
| Customer messaged you recently (open session) | POST /messages (text, media, interactive, location…) |
POST /messages |
| You start the conversation / session expired | POST /templates/send only |
POST /messages (no Meta template requirement) |
| OTP, utility alerts, invoices outside 24h | Approved UTILITY / AUTHENTICATION template | Session message if channel policy allows |
| Marketing broadcast | Approved MARKETING template + opt-out rules | Use cautiously; respect local policy |
Recommended SaaS flow
- Receive
message.receivedwebhook → open/refresh your local session timer for that contact + channel. - If session open → reply with
POST /messages. - If session closed on Cloud → send an approved template, then continue free-form after the customer replies.
- Never assume a global “open inbox”; sessions are per contact and WhatsApp number.
Template categories you will use most
- UTILITY — invoices, shipping, account notices (often with DOCUMENT header or URL body).
- AUTHENTICATION — OTP / login codes.
- MARKETING — promotions; may return
marketing_suppressedwhen the contact opted out.