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

Using Amazon SNS Message Attributes

Amazon Simple Notification Service (Amazon SNS) provides support for delivery of message attributes to Amazon SQS endpoints. Message attributes allow you to provide structured metadata items (such as timestamps, geospatial data, signatures, and identifiers) about the message. Message attributes are optional and separate from, but sent along with, the message body to Amazon SQS endpoints. This information can be used by the receiver of the message to help decide how to handle the message without having to first process the message body. Each message can have up to 10 attributes. To specify message attributes, you can use the AWS software development kits (SDKs) or query API.

Important

To use message attributes with Amazon SQS endpoints, you must set the subscription attribute, Raw Message Delivery, to True. For more information about Raw Message Delivery, see Appendix: Large Payload and Raw Message Delivery

You can also use message attributes to help structure the push notification message for mobile endpoints. In this scenario the message attributes are only used to help structure the push notification message and are not delivered to the endpoint, as they are when sending messages with message attributes to Amazon SQS endpoints.

Message Attribute Items and Validation

Each message attribute consists of the following items:

  • Name – The message attribute name can contain the following characters: A-Z, a-z, 0-9, underscore(_), hyphen(-), and period (.). The name must not start or end with a period, and it should not have successive periods. The name is case sensitive and must be unique among all attribute names for the message. The name can be up to 256 characters long. The name cannot start with "AWS." or "Amazon." (or any variations in casing) because these prefixes are reserved for use by Amazon Web Services.

  • Type – The supported message attribute data types are String, Number, and Binary. The data type has the same restrictions on the content as the message body. The data type is case sensitive, and it can be up to 256 bytes long. For more information, see the Message Attribute Data Types and Validation section.

  • Value – The user-specified message attribute value. For string data types, the value attribute has the same restrictions on the content as the message body. For more information, see the Publish action in the Amazon Simple Notification Service API Reference.

Name, type, and value must not be empty or null. In addition, the message body should not be empty or null. All parts of the message attribute, including name, type, and value, are included in the message size restriction, which is currently 256 KB (262,144 bytes).

Message Attribute Data Types and Validation

Message attribute data types identify how the message attribute values are handled by Amazon SNS. For example, if the type is a number, Amazon SNS will validate that it's a number.

Amazon SNS supports the following logical data types:

  • String – Strings are Unicode with UTF-8 binary encoding. For a list of code values, see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters.

  • Number – Numbers are positive or negative integers or floating-point numbers. Numbers have sufficient range and precision to encompass most of the possible values that integers, floats, and doubles typically support. A number can have up to 38 digits of precision, and it can be between 10^-128 to 10^+126. Leading and trailing zeroes are trimmed.

  • Binary – Binary type attributes can store any binary data, for example, compressed data, encrypted data, or images.

Reserved Message Attributes

The following table lists the reserved message attributes for push notification services that you can use to structure your push notification message:

Push Notification Service Reserved Message Attribute Allowed Values

Baidu

AWS.SNS.MOBILE.BAIDU.DeployStatus (optional)

AWS.SNS.MOBILE.BAIDU.MessageType (optional)

AWS.SNS.MOBILE.BAIDU.MessageKey (optional)

1—development environment. 2—production environment. (default 1)

0—in-app message. 1—alert notification. (default 1)

A short message identifier you can attach to your message

MPNS

AWS.SNS.MOBILE.MPNS.Type (required)

AWS.SNS.MOBILE.MPNS.NotificationClass (required)

token (for tile notifications), toast, raw

realtime, priority, regular

WNS

AWS.SNS.MOBILE.WNS.Type (required)

AWS.SNS.MOBILE.WNS.CachePolicy (optional)

AWS.SNS.MOBILE.WNS.Group (optional)

AWS.SNS.MOBILE.WNS.Match (optional)

AWS.SNS.MOBILE.WNS.SuppressPopup (optional)

AWS.SNS.MOBILE.WNS.Tag (optional)

same as X-WNS-Type

same as X-WNS-Cache-Policy

same as X-WNS-Group

same as X-WNS-Match

same as X-WNS-SuppressPopup

same as X-WNS-Tag

For more information about using message attributes with Baidu, see Using Message Attributes for Structuring the Message.

Using Message Attributes with the AWS SDKs

The AWS SDKs provide APIs in several languages for using message attributes with Amazon SNS. Java examples with message attributes are in the AWS sample file SNSMobilePush.java, which is included in the snsmobilepush.zip file.

When setting message attributes for a message, you can use either a string value or a binary value, but not both string and binary values.

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