Amazon Simple Notification Service
Developer Guide (API Version 2010-03-31)

Using the Amazon SNS Time To Live (TTL) Message Attribute for Mobile Push Notifications

Amazon Simple Notification Service (Amazon SNS) provides support for setting a Time To Live (TTL) message attribute for mobile push notifications messages. This is in addition to the existing capability of setting TTL within the Amazon SNS message body for the mobile push notification services that support this, such as Amazon Device Messaging (ADM) and Google Cloud Messaging for Android (GCM).

The TTL message attribute is used to specify expiration metadata about a message. This allows you to specify the amount of time that the push notification service, such as Apple Push Notification Service (APNS) or GCM, has to deliver the message to the endpoint. If for some reason (such as the mobile device has been turned off) the message is not deliverable within the specified TTL, then the message will be dropped and no further attempts to deliver it will be made. To specify TTL within message attributes, you can use the AWS Management Console, AWS software development kits (SDKs), or query API.

TTL Message Attributes for Push Notification Services

The following is a list of the TTL message attributes for push notification services that you can use to set when using the AWS SDKs or query API:

Push Notification Service TTL Message Attribute
Amazon Device Messaging (ADM) AWS.SNS.MOBILE.ADM.TTL
Apple Push Notification Service (APNS) AWS.SNS.MOBILE.APNS.TTL
Apple Push Notification Service Sandbox (APNS_SANDBOX) AWS.SNS.MOBILE.APNS_SANDBOX.TTL
Baidu Cloud Push (Baidu) AWS.SNS.MOBILE.BAIDU.TTL
Google Cloud Messaging for Android (GCM) AWS.SNS.MOBILE.GCM.TTL
Windows Push Notification Services (WNS) AWS.SNS.MOBILE.WNS.TTL

Each of the push notification services handle TTL differently. Amazon SNS provides an abstract view of TTL over all the push notification services, which makes it easier to specify TTL. When you use the AWS Management Console to specify TTL (in seconds), you only have to enter the TTL value once and Amazon SNS will then calculate the TTL for each of the selected push notification services when publishing the message.

TTL is relative to the publish time. Before handing off a push notification message to a specific push notification service, Amazon SNS computes the dwell time (the time between the publish timestamp and just before handing off to a push notification service) for the push notification and passes the remaining TTL to the specific push notification service. If TTL is shorter than the dwell time, Amazon SNS won't attempt to publish.

If you specify a TTL for a push notification message, then the TTL value must be a positive integer, unless the value of 0 has a specific meaning for the push notification service—such as with APNS and GCM. If the TTL value is set to 0 and the push notification service does not have a specific meaning for 0, then Amazon SNS will drop the message. For more information about the TTL parameter set to 0 when using APNS, see Table A-3 Item identifiers for remote notifications in the Binary Provider API documentation. For more information about the TTL parameter set to 0 when using GCM, see Lifetime of a message.

Precedence Order for Determining TTL

The precedence that Amazon SNS uses to determine the TTL for a push notification message is based on the following order, where the lowest number has the highest priority:

  1. Message attribute TTL

  2. Message body TTL

  3. Push notification service default TTL (varies per service)

  4. Amazon SNS default TTL (4 weeks)

If you set different TTL values (one in message attributes and another in the message body) for the same message, then Amazon SNS will modify the TTL in the message body to match the TTL specified in the message attribute.

Specifying TTL with the AWS Management Console

You can specify TTL with the AWS Management Console.

  1. Sign in to the AWS Management Console and open the Amazon SNS console at

  2. In the left Navigation pane, click Apps, and then click the app containing the endpoints you want to set TTL for when publishing a message.

  3. Select the endpoints to publish a message to, click Endpoint Actions and then click Publish.

  4. On the Publish dialog box, enter the number of seconds for Time to Live (TTL) and then click Publish Message.

Specifying TTL with the AWS SDKs

The AWS SDKs provide APIs in several languages for using TTL with Amazon SNS.

For more information about the SDK for Java, see Getting Started with the AWS SDK for Java.

The following Java example shows how to configure a TTL message attribute and publish the message to an endpoint, which in this example is registered with Baidu Cloud Push:

Map<String, MessageAttributeValue> messageAttributes = new HashMap<String, MessageAttributeValue>(); // Insert your desired value (in seconds) of TTL here. For example, a TTL of 1 day would be 86,400 seconds. messageAttributes.put("AWS.SNS.MOBILE.BAIDU.TTL", new MessageAttributeValue().withDataType("String").withStringValue("86400")); PublishRequest publishRequest = new PublishRequest(); publishRequest.setMessageAttributes(messageAttributes); String message = "{\"title\":\"Test_Title\",\"description\":\"Test_Description\"}"; publishRequest.setMessage(message); publishRequest.setMessageStructure("json"); publishRequest.setTargetArn("arn:aws:sns:us-east-1:999999999999:endpoint/BAIDU/TestApp/318fc7b3-bc53-3d63-ac42-e359468ac730"); PublishResult publishResult = snsClient.publish(publishRequest);

For more information about using message attributes with Amazon SNS, see Using Amazon SNS Message Attributes.