Skip to content

Template Time-to-Live(TTL)

Also called: Message TTL · message_send_ttl_seconds · Template message validity period

Definition
How long WhatsApp keeps trying to deliver a template message before dropping it: 10 minutes by default for OTPs, 30 days for utility and marketing.

Exhibit A

Watch delivery attempts run out against the TTL

7 / 7

Retries exhausted

t = 5 min 10 s

Gave upTTL reached: message dropped, no delivered status
  1. Attempt 1 at 0 ms: failed.
  2. Attempt 2 at 10 s, after waiting 10 s: failed.
  3. Attempt 3 at 30 s, after waiting 20 s: failed.
  4. Attempt 4 at 1 min 10 s, after waiting 40 s: failed.
  5. Attempt 5 at 2 min 30 s, after waiting 1 min 20 s: failed.
  6. Attempt 6 at 5 min 10 s, after waiting 2 min 40 s: failed.
  7. TTL reached: message dropped, no delivered statusafter 6 attempts · t = 5 min 10 s

The delay formula

delayn = base × factorn

All 5 retries are spent (6 attempts in 5 min 10 s), so the client stops: TTL reached: message dropped, no delivered status.

24 clients, same outage · retry n = 4

Without jitter all 24 retry at exactly 2 min 40 s: a thundering herd that can knock the server over again.

An illustrative 5-minute OTP to a phone with no signal: attempts space out until the TTL is reached and the message is dropped. Meta does not publish its real retry schedule; the deadline is what you control.

Gave up after 6 attempts at 5 min 10 s: TTL reached: message dropped, no delivered status.

What is template time-to-live (TTL)?

Template time-to-live (TTL) is the delivery deadline for a template message. If the recipient's phone is off, out of coverage or has not connected, WhatsApp keeps trying to deliver the message — but only until the TTL runs out. After that the message is dropped and never arrives. The TTL is a property of the template, set with message_send_ttl_seconds when you create or edit it, in 1-second steps.

Defaults and allowed ranges depend on the category. Authentication templates default to 10 minutes and can be set from 30 seconds to 15 minutes; those created before 23 October 2024 default to 30 days. Utility templates default to 30 days and can be set from 30 seconds to 12 hours on the Cloud API. Marketing templates default to 30 days and can be set from 12 hours to 30 days on the Marketing Messages API for WhatsApp. For authentication and utility, the value -1 sets a custom TTL of 30 days.

TTL is not the 24-hour customer service window, which governs what you may send, and not code_expiration_minutes, which is the expiry an authentication message displays. TTL only governs how long delivery is attempted. Do not wait for a dedicated expiry event: Meta's guidance is that if no delivered status arrives within the TTL, you should assume the message was dropped — allowing a small buffer, because a failed status can arrive with a slight delay.

Key takeaways

  • Template time-to-live (TTL) is how long WhatsApp keeps trying to deliver a template message before dropping it.
  • Authentication templates default to 10 minutes (30 seconds to 15 minutes); utility and marketing default to 30 days.
  • Utility TTL can be set from 30 seconds to 12 hours and marketing from 12 hours to 30 days, with message_send_ttl_seconds.
  • If no delivered status arrives within the TTL plus a small buffer, treat the message as dropped and use your fallback.
  • TTL is unrelated to the 24-hour customer service window, which decides what you may send, not how long delivery is tried.

How does template time-to-live (TTL) work?

  1. Set it on the template

    Include message_send_ttl_seconds in POST /{WABA_ID}/message_templates, within the range for the template's category. Leave it out to keep the default.

  2. Send as usual

    The send request does not change. The template's TTL applies to every message sent with it.

  3. WhatsApp keeps trying while the phone is unreachable

    Delivery is attempted until the message reaches the device or the TTL runs out. Meta does not publish its retry schedule.

  4. Delivered, or dropped at expiry

    If the device connects in time you receive delivered (and perhaps read). If not, the message is dropped; you are billed only for delivered messages.

  5. Your watchdog decides the fallback

    Start a timer at send time slightly longer than the TTL. If no delivered status has arrived when it fires, mark the message expired and use your fallback channel.

Why does template time-to-live (TTL) matter?

A late message can be worse than none. A login code that lands 40 minutes after the user gave up is useless and confusing, and because billing is per delivered message it is still paid for. A flash-sale message delivered the day after the sale invites blocks. Short, category-appropriate TTLs make undeliverable messages fail cleanly, so your system can fall back to SMS or voice while the user is still waiting.

Template time-to-live (TTL) in code

curl -X POST "https://graph.facebook.com/v26.0/{WABA_ID}/message_templates" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "login_code",
    "language": "en",
    "category": "AUTHENTICATION",
    "message_send_ttl_seconds": 300,
    "components": [
      { "type": "body", "add_security_recommendation": true },
      { "type": "footer", "code_expiration_minutes": 5 },
      { "type": "buttons", "buttons": [
        { "type": "otp", "otp_type": "copy_code", "text": "Copy code" }
      ] }
    ]
  }'

TTL (300 s) equals the code's validity (5 min), so a stale code is never delivered.

Example: An OTP fallback for a Pune lending app

A Pune lending app sends login codes with an authentication template whose code_expiration_minutes is 5 and message_send_ttl_seconds is 300. A user on a train through the ghats requests a code with no data signal. WhatsApp cannot reach the phone, and at five minutes the message is dropped instead of arriving later as a stale code. The app's watchdog sees no delivered status at 5 minutes 30 seconds and sends the code by SMS, which reaches the phone at the next tower.

Common mistakes with template time-to-live (TTL)

  • A TTL longer than the code's validity

    A code that expires in 5 minutes should not be deliverable for 15. Keep the TTL at or below code_expiration_minutes on authentication templates.

  • Waiting for an expiry event

    Meta documents no dedicated TTL-expired event. Treat the absence of delivered within the TTL plus a small buffer as a drop.

  • Utility defaults on time-bound alerts

    A utility template left at the 30-day default can deliver a "your cab is arriving" alert days later. Set a TTL that matches the event, up to 12 hours.

  • Losing the TTL in a recategorisation

    If Meta moves a template to another category, message_send_ttl_seconds is set to null. Re-apply a TTL within the new category's range.

  • Confusing TTL with the service window

    TTL only limits delivery attempts. Whether you may send a free-form message at all is decided by the 24-hour customer service window.

Best practices for template time-to-live (TTL)

  • Pair every short TTL with a fallback channel and a watchdog.
  • Log the time from send to delivered; it shows whether your TTL is cutting off deliveries that would have been useful.
  • Use long marketing TTLs only for evergreen content and shorten them for dated offers.
  • Re-check each template's TTL after any category change.

TTL FAQs

Am I charged for a message that expires?+
You are billed for delivered messages. A message dropped at the end of its TTL was never delivered.
Can I set a different TTL for each message?+
Meta documents TTL as a template setting, `message_send_ttl_seconds`. If two flows need different deadlines, use two templates.
My OTP template is older than October 2024. What is its TTL?+
Authentication templates created before 23 October 2024 default to 30 days. Set `message_send_ttl_seconds` explicitly so old codes are not delivered long after they expire.
Why didn't I get a failed status when the TTL ran out?+
Meta does not guarantee one at expiry, and a failure status can arrive late. Assume the message was dropped if no delivered status arrives within the TTL plus a buffer.

See InfiQ pricing

Try it on the official WhatsApp Business API

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms