WhatsApp Business Platform

Configure message time-to-live (TTL)

Updated: Jul 31, 2026
Copy for LLM
Note. Custom time-to-live (TTL) is only supported with Direct Send.
You can configure TTL when calling POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages by adding a ttl_seconds field below the category field.

Example request

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "text",
  "text": {
    "body": "<BODY_TEXT>"
  },
  "category": "utility",
  "ttl_seconds": 600
}
Note. TTL works with both utility and authentication messages. Set category to the value you need. Defaults and limits differ by category — see the table below.

TTL defaults and limits

TTL defaults and limits depend on the message category. Direct Send supports utility and authentication messages.
CategoryDefaultMinimumMaximum
utility
30 days
30 seconds
43200 seconds (12 hours)
authentication
600 seconds (10 minutes)
30 seconds
900 seconds (15 minutes)
Authentication messages use a much shorter default and maximum than utility messages, because authentication codes are time-sensitive.

Success response

When a message with TTL is sent successfully, you receive the normal message-success response:
{
  "messaging_product": "whatsapp",
  "contacts": [{
    "input": "PHONE_NUMBER",
    "wa_id": "WHATSAPP_ID"
  }],
  "messages": [{
    "id": "wamid.ID"
  }]
}

Failure response

Messages configured with TTL can fail when:
  • You use TTL on a message that isn’t a Direct Send message.
  • The TTL expires before the message can be delivered.
  • The TTL value is too high or too low.
CaseResponse
TTL set on a non-Direct Send message
Returns error code 100 “Invalid parameter” — “The request included one or more unsupported or misspelled parameters.”
Message undeliverable within TTL
The message is dropped.
TTL value above the category maximum
Returns error code 100 — “The time to live value must be lower than or equal to <MAX>”, where <MAX> is the category maximum (43200 for utility, 900 for authentication).
TTL value below the category minimum
Returns error code 100 — “The time to live value must be higher than or equal to 30.”