# Configure message time-to-live (TTL)


**Note:** The Direct Send API is in beta. Features and behavior described here are subject to change and may be released incrementally. Participation is subject to acceptance of the beta terms.

> **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

```html
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.

| Category | Default | Minimum | Maximum |
|----------|---------|---------|---------|
| `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:

```json
{
  "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.

| Case | Response |
|------|----------|
| TTL set on a non-Direct Send message | Returns [error code 100 "Invalid parameter"](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/#other-errors) — "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](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/#other-errors) — "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](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/#other-errors) — "The time to live value must be higher than or equal to 30." |

## Related

- [Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/direct-send/api-reference)