- Obtained and stored the app instance’s registration ID. For information on the app-side of this process, see Integrate Your App.
- Exchanged your client credentials for a current access token. For details, see Request an Access Token.
Send a test message in the Developer Console
You can set up test messages for ADM in the Developer Console. To set up a test notification- Sign in to the Developer Console.
- From the navigation bar, select Tools & Services > Amazon Device Messaging.
- On the Test your message screen, enter the Client ID and secret and Device registration ID.
- Choose the duration of the message in the Message expires after section.
-
Choose the message type.
- Data message – key-value pair required.
- Notification message – title and content required, other fields optional.
- Data & Notification message – key-value pair and title and content required, other fields optional.
- To complete your notification, select Send test message.
Message payloads and uniqueness
Using ADM, you can send messages with a payload of up to 6 KB in size. For example, an instant-message program might send a message with a payload like the following.data parameter and include a value for the consolidationKey parameter. The consolidation key allows ADM to identify sync messages with redundant payloads and attempt to deliver only one of the messages to your app.
consolidationKey parameter to allow ADM to consolidate messages, when possible.
Request format
To send a message, your server component (from now on referred to as “your server”) issues an HTTP POST request that looks similar to the following.| Field | Description | Example |
|---|---|---|
Authorization | Include your current access token here. Value must be: Bearer (YOUR_ACCESS_TOKEN) | Authorization: Bearer Atc|<Your access Token> |
Content-Type | Value must be: application/json | Content-Type: application/json |
X-Amzn-Type-Version | Value must be: com.amazon.device.messaging.ADMMessage@1.0 | X-Amzn-Type-Version: com.amazon.device.messaging.ADMMessage@1.0 |
Accept | Value must be: application/json | Accept: application/json |
X-Amzn-Accept-Type | Value must be: com.amazon.device.messaging.ADMSendResult@1.0 | X-Amzn-Accept-Type: com.amazon.device.messaging.ADMSendResult@1.0 |
| Parameter | Description | Example |
|---|---|---|
data | The payload data to send with the message. The data must be in the form of JSON-formatted key-value pairs; both keys and values must be String values. The total size of the data can’t be greater than 6 KB. The total size includes the keys and values, the quotes that surround them, the ”:” character that separates them, the commas that separate the pairs, and the opening and closing brace around the field. Whitespaces between key-value pairs aren’t included in the calculation of payload size.If the message doesn’t include payload data, such as with a sync message, you can pass in an empty object, for example, "data":{}. | "data":{ "from":"Sam", "message":"Hey, Max. How are you?", "time":"10/26/2012 09:10:00" } |
priority | Optional value. There are two values for the priority of messages being sent: normal and high priority. The default priority is normal. ADM can deliver normal priority messages immediately if the app is in the foreground. When the device is in doze mode, delivery might be delayed until the next maintenance window. For high priority messages, ADM attempts to deliver the message to the app immediately even when in doze mode. The number of high priority messages an app can receive in a day is limited by the app’s standby bucket. | "priority": "high" |
consolidationKey | Optional value. An arbitrary string used to indicate that multiple messages are logically the same, and that ADM can drop previously enqueued messages in favor of this new one. There are no guarantees that ADM won’t deliver the previously enqueued messages. Your consolidation key can’t be greater than 64 characters in length. | "consolidationKey":"SyncNow" |
expiresAfter | Optional value. The number of seconds that ADM should retain the message if the device is offline. After this time, ADM can discard the message. Allowed values range from 60 (1 minute) to 2678400 (31 days), inclusive. The default value is 604800 (1 week). For ADM on Fire OS devices, the maximum supported value is 31 days. | "expiresAfter":86400 |
md5 | Optional value. This is a base-64-encoded MD5 checksum of the data parameter. If you provide a value for the md5 parameter, ADM verifies its accuracy. If you do not provide a value, the server calculates the value on your behalf. In either case, the server passes the md5 parameter’s value through to the device and returns the calculated value within the x-amzn-data-md5 response header. | See an example of calculating an MD5 checksum in the ADM Sample Code folder. |
md5 value matches that from ADM servers, you should calculate a value for this parameter as follows:
- Sort the message’s key-value pairs using a UTF-8 code unit-based comparison of the keys.
- Concatenate the series of pairs in the format:
"key1:value1,key2:value2". - Remove any white spaces between the key/value pairs. There should be no whitespace between the ’:’ character and either the keys or values. There should also be no whitespace in between each pair and the ’,’ character.
- Compute the SHA-256 value using the UTF-8 bytes of the resulting string, according to the algorithm defined in RFC 1321.
- Base-64 encode the 128-bit output of the computation.
Response format
After successfully receiving and interpreting your POST request message, ADM servers send an HTTP response message that looks similar to the following.registrationID: The current registration ID of the app instance. If this value is different from the one passed in by your server, your server must update its records to use this value.
reason: The reason the request was not accepted.
| Code | Description | Example |
|---|---|---|
400 | Some argument of the input was invalid. Possible status codes include: InvalidRegistrationId, InvalidData, InvalidConsolidationKey, InvalidExpiration, InvalidChecksum, InvalidType, and Unregistered. Unregistered indicates that the app instance associated with the registration ID is no longer available to receive messages. You can receive an Unregistered status code if the owner of the device on which the app instance is registered has changed, or if the app instance has requested to no longer receive messages. InvalidRegistrationId indicates that the registration ID does not correspond to the sender identified by the provided access token. | "reason": "InvalidRegistrationId" |
401 | The access token provided was invalid. The sender should refresh their access token. For information about refreshing an access token, see Request an Access Token. | "reason":"AccessTokenExpired" |
413 | The message payload provided in the data parameter exceeded the maximum allowable data size (6 KB). | "reason":"MessageTooLarge" |
429 | The requester has exceeded their maximum allowable rate of messages. The sender might retry later honoring the Retry-After header included in the response. To ensure high availability, ADM limits the number of messages that can be sent over a given period of time. If you have specific capacity requirements, please contact us and provide the following information with your request: your name, company name, your email address, requested TPS (transactions per second) limit, reason. | "reason":"MaxRateExceeded" |
500 | There was an internal server error. The requester must retry later honoring the Retry-After header included in the response. | n/a |
503 | The server is temporarily unavailable. The requester must retry later honoring the Retry-After header included in the response. | n/a |
| Field | Description | Example |
|---|---|---|
X-Amzn-Data-md5 | The calculated base-64-encoded MD5 checksum of the data field. | X-Amzn-Data-md5: <md5 checksum> |
X-Amzn-RequestId | A value created by ADM that uniquely identifies the request. If you have problems with ADM, Amazon can use this value to troubleshoot the problem. | X-Amzn-RequestId: <hexidecimal request ID> |
Retry-After | Error responses with HTTP status codes of 429, 500, or 503 include this field. Retry-After specifies how long the service is expected to be unavailable. This value can be either an integer number of seconds (in decimal) after the time of the response or an HTTP-format date. For possible formats for this value, see the HTTP/1.1 specification, section 10.2.3. | Retry-After: 120 |
Content-Type | The content type of the resource: application/json | Content-Type: application/json |
X-Amzn-Type-Version | Describes the format of the response. | X-Amzn-Type-Version: com.amazon.device.messaging.ADMSendResult@1.0 |

