If a message cannot be delivered to a WhatsApp user, delivery is retried for a period of time known as time-to-live (“TTL”), or the message validity period.

You can customize the default TTL for authentication and utility templates sent via Cloud API, and for marketing templates sent via Marketing Messages API for WhatsApp.

Set a TTL for all authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable.

Defaults, min/max values, and compatibility table

	Authentication	Utility	Marketing
Default TTL	10 minutes 30 days for authentication templates created before October 23, 2024	30 days	30 days
Compatibility	Cloud API	Cloud API only	Marketing Messages API for WhatsApp
Customizable range	30 seconds to 15 minutes	30 seconds to 12 hours	12 hours to 30 days

Customize the TTL

To set a custom TTL on an authentication, utility, or marketing template, include the message_send_ttl_seconds property in the POST /<PHONE_NUMBER_ID>/message_templates call.

You can change the TTL on a previously configured template using this method, as well.

TTL can be customized in 1 second increments.

Valid `message_send_ttl_seconds` property values

Authentication templates: 30 to 900 seconds (30 seconds to 15 minutes)

Utility templates: 30 to 43200 seconds (30 seconds to 12 hours)

Marketing templates: 43200 to 2592000 (12 hours to 30 days)

For authentication and utility templates, you can set the message_send_ttl_seconds property value to -1, which will set a custom TTL of 30 days.

Example request

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates' \
      -H 'Authorization: Bearer EAAJB...' \
      -H 'Content-Type: application/json' \
      -d '
      {
        "name": "test_template",
        "language": "en_US",
        "category": "MARKETING",
        "message_send_ttl_seconds": 120,
        "components": [
          {
            "type": "BODY",
            "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
            "example": {
              "body_text": [
                [
                  "the end of August","25OFF","25%"
                ]
              ]
            }
          },
          {
            "type": "FOOTER",
            "text": "Use the buttons below to manage your marketing subscriptions"
          },
        ]
      }'

Sample response

{
  "id": "572279198452421",
  "status": "PENDING",
  "category": "MARKETING"
}

When TTL is exceeded

The system drops messages that cannot be delivered within the default or customized TTL.

If you do not receive a delivered message webhook before the TTL is exceeded, assume the message was dropped.

If you send a message that fails to deliver, there could be a minor delay before you receive the webhook, so you may wish to build in a small buffer before assuming the message was dropped.

TTL reset on automatic category updates

If a template is reclassified by an automatic category update, the TTL value is cleared by setting it to a null value. You can reset the TTL to any value within the customizable range for the new template category, as listed in the Defaults, min/max values, and compatibility table.

For example, if a utility template with a custom TTL of 12 hours is reclassified as a marketing template, the custom TTL is cleared (message_send_ttl_seconds = null). At this point, you can set the TTL to any value between 12 hours and 30 days, which is the customizable range for marketing templates, as listed in the table above.

See Template categorization for more details about WABA message template categories and associated workflows.

Did you find this page helpful?

Configure message time-to-live