In the world of real-time communication, timing is everything. Whether you’re sending a one-time password (OTP), a shipment update, or a limited-time offer, it’s critical that your message reaches your customer while it’s still relevant. This is where Time-To-Live (TTL) in WhatsApp Business API templates becomes important.
⸻
✅ What is TTL?
TTL, or Time-To-Live, refers to the duration WhatsApp will keep retrying to deliver a message to a user who is temporarily unreachable (for example, if their phone is off or they are out of network coverage). If the message is not delivered within this TTL window, it is dropped and will not be delivered later.
In technical terms, TTL is also referred to as the message validity period.
⸻
🔧 Why is TTL Important?
Setting a suitable TTL ensures:
• Customers don’t receive outdated or irrelevant messages.
• OTPs and other authentication messages are only delivered when the code is still valid.
• You avoid confusion and improve the user experience by sending timely information.
⸻
📊 TTL Defaults, Limits, and Compatibility
Here’s a quick breakdown of TTL behavior by template type:
| Template Type | Default TTL | Customizable Range | API Compatibility |
|---|---|---|---|
| Authentication | 10 minutes | 30 seconds – 15 minutes | Cloud API + On-Premise API |
| Utility | 30 days | 30 seconds – 12 hours | Cloud API only |
| Marketing | 30 days | 12 hours – 30 days | Marketing Messages (MM) Lite API |
🛑 Note: Authentication templates created before October 23, 2024, default to a 30-day TTL unless explicitly updated.
⸻
✍️ How to Set or Update TTL
To customize TTL, include the message_send_ttl_seconds parameter when creating or editing a template from the UI.
• TTL is defined in seconds
• You can use 1-second increments for fine-grained control
• TTL can be updated even on existing templates
🔢 Valid Ranges by Template Type:
• Authentication: 30 to 900 seconds (30 seconds to 15 minutes)
• Utility: 30 to 43,200 seconds (30 seconds to 12 hours)
• Marketing: 43,200 to 2,592,000 seconds (12 hours to 30 days)
⸻
📉 What Happens When TTL Expires?
If a message cannot be delivered within the defined TTL:
• It is dropped (not delivered at all).
• You will not receive a messages.delivered webhook.
• There may be a small delay in receiving the final webhook confirming the drop, so it’s good practice to include a slight buffer in your application logic.
⸻
🎯 Best Practices
• Always set a custom TTL for authentication templates, and match or stay below your OTP/code expiration time.
• Use short TTLs for critical utility updates like payment or delivery alerts.
• For marketing messages, consider your campaign duration and user engagement window before setting TTL.⸻
📬 In Summary
| Feature | Benefit |
|---|---|
| Customizable TTL | Fine-tune delivery windows by template type |
| Prevents Irrelevance | Messages dropped if no longer timely |
| Flexible Integration | 1-second granularity and API-based config |
Using TTL smartly ensures your WhatsApp messages are timely, relevant, and effective—helping you build trust and deliver a better experience to your users.
⸻
