Template messages vs session messages
| Template message | Session message | |
|---|---|---|
| Requires pre-approval | Yes — approved in Meta’s WhatsApp Manager | No |
| 24-hour window | Not restricted | Customer must have messaged you first within 24 hours |
| Use for | Proactive outreach, notifications, campaigns | Replies, real-time support, conversations |
| Endpoint | POST …/send/whatsapp_templated_messages | POST …/send/messages |
When in doubt: use a template message to start a conversation, use a session message to continue one.
How it works
Create and approve a template
Build your message template in Meta’s WhatsApp Manager and submit it for approval. Once approved, you can reference it by name in the API. See Template management for how to create templates via the API.
Send a template message to initiate contact
Use Send template message to reach out to a customer. This works at any time — no prior interaction needed. The response includes a message ID you can use to track delivery.
Reply with a session message
Once the customer replies, a 24-hour session window opens. Use Send session message to respond with free-form text, media, location pins, interactive lists, reply buttons, or product catalog messages.
Track delivery via webhooks
Subscribe to webhooks to receive real-time delivery status events (
sent, delivered, read, delivery_failed) and inbound message events.Message types at a glance
Template messages support:- Text, image, video, and document headers
- Body variables (
body_1…body_15) - URL buttons with dynamic suffixes
- Carousel cards with per-card media, body, and buttons
- Multi-language translations
- Plain text
- Image, video, audio, and document attachments
- Location pins
- Interactive list messages
- Interactive reply-button messages
- Single and multi-product catalog messages
Endpoints
Send template message
POST …/send/whatsapp_templated_messages — initiate contact or reach customers outside the 24-hour window.Send session message
POST …/send/messages — reply within an active session with any content type.Error codes
Full reference for error types and codes returned by the messaging endpoints.
Business-scoped user IDs
How to send and receive messages for customers identified by BSUID instead of phone number.