Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Develop
Test
Publish
Monetize
Engage users
Device specifications
Resources
Skip to main content
Topic-Based Messaging (TBM) uses multicast communication to send messages to groups of users who subscribe to the same topic. When a user installs an app on a device, the app instance receives a unique identifier called a device registration ID. In ADM, you can use this ID to deliver a message to an individual device. However, with Topic-Based Messaging, you can send messages to multiple app instances in a single API call. Instead of sending a message to an individual device registration ID, you send a message to a topic. Users subscribe to that topic, and Amazon Device Messaging (ADM) routes the messages to all device registration IDs associated with that topic. Message types include data messages, notification messages, and notification messages with data. You can use topics to engage with particular segments of your customers. For example, if you developed a weather forecasting app, users could opt in to a topic for their geographical location and receive notifications for changes in the weather in their area. For a video streaming app, users could subscribe to their genres of interest to get automatic updates whenever a new movie or series of that genre releases.

Considerations for Topic-Based Messaging

Here are some important considerations about Topic-Based Messaging:
  • Topic-Based Messaging targets a specific security profile. This means that when multiple apps share the same security profile, Topic-Based Messaging can reach all app instances associated with that security profile.
  • Amazon Device Messaging (ADM) enforces these limits in working with topics:
    • One security profile can have a maximum of 100 topics allocated to it.
    • One app instance can subscribe to a maximum of 100 topics.
    • One topic can have a maximum of 10,000 app instances subscribed to it.
  • Topic-Based Messaging strives for higher throughput rather than lower latency. To send messages to individual devices, target messages to device registration IDs instead of topics.
  • Topic-Based Messaging is best for publicly available resources, such as weather forecasts, and stock quotes.

Register a security profile for Topic-Based Messaging

With Topic-Based Messaging, you can do the following:
  • Subscribe a device registration ID to a topic
  • Unsubscribe a device registration ID from a topic
  • Send a message to a topic

Prerequisites

To use Topic-Based Messaging, complete these prerequisites.
  • Obtain and store the app instance’s registration IDs. For information about the app-side of this process, see Integrate Your App.
  • Exchange your client credentials for a current access token. For details, see Request an Access Token.
After you meet these prerequisites, you can register the security profile associated with the generated access token for Topic-Based Messaging programmatically.

Request format

To register your security profile with Topic-Based Messaging, your server component (from now on referred to as “your server”) must issue an HTTP POST request as shown in the following example.
To get the complete POST URL, combine the second line (Host) and the first line (POST) as shown here.

Request requirements

The request itself consists of two parts: the header and message body.

Header fields

The header must contain the following fields.
FieldDescriptionExample
AuthorizationInclude your current access token here. Value must be: Bearer (YOUR_ACCESS_TOKEN)Authorization: Bearer <Your access token>
Content-TypeValue must be: application/jsonContent-Type: application/json
AcceptValue must be: application/jsonAccept: application/json

Message body parameter

For the message body content, provide a JSON object with a string containing the following parameters.
ParameterDescriptionExample
clientSecretThe “client secret” portion of your client credentials.clientSecret=<YOUR_CLIENT_SECRET>

Response format

After successfully receiving and interpreting your POST request message, ADM servers send an HTTP response message similar to the following.
ADM returns an HTTP 200 status code if the security profile for the client credentials is registered with Topic-Based Messaging. If you receive a 200 status code, the response message contains the following parameter in a JSON object:
  • message: Contains the security profile associated with the credentials you used to create the access token, and the clientSecret parameter used in the message body. The response should be that the security profile is now registered with Topic-Based Messaging.
ADM returns an error code if the security profile for the client credentials isn’t registered with Topic-Based Messaging. For a code other than 200, the response message might contain this parameter in the JSON object body:
  • reason: The reason the request was not accepted
For a description of the HTTP error status codes, see the following section.

ADM HTTP error status codes

HTTP status codeDescriptionExample
400The clientSecret in the message body isn’t the same as the one used to create the access token. The sender should use the same clientSecret in the message body as the one used to create the access token."reason": "The given clientSecret is not associated with the security profile amzn1.application.<32 hexadecimal characters>"
401The 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"
429The requester has exceeded their maximum allowable message rate. The sender can retry later according to the Retry-After header directions included in the response. To ensure high availability, ADM limits the number of messages sent over a given period of time. If you have specific capacity requirements, contact us and provide the following information:
- your name
- company name
- your email address
- requested TPS (transactions per second) limit
- reason
"reason":"MaxRateExceeded"
500There was an internal server error. The requester can retry later according to the Retry-After header included in the response.n/a
503The server is temporarily unavailable. The requester can try later according to the Retry-After header directions included in the response.n/a

Response header fields

FieldDescriptionExample
X-Amzn-RequestIdA 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: <Amazon RequestId>
Retry-AfterError responses with HTTP status codes of 429, 500, or 503 include this field. The Retry-After message specifies how long the service is expected to be unavailable. This value can be either a decimal number of seconds 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: 30
Content-TypeThe resource content type: application/jsonContent-Type: application/json

Make a TBM registration request

Here is an example of how your server software might make a request to register a security profile with Topic-Based Messaging, and handle the ADM server response.

Subscribe or unsubscribe the client app instance to a topic

Client apps can subscribe to any existing topic or create a new topic. When a client app subscribes to a new topic that doesn’t exist in the associated security profile, a new topic is created. Any app associated with that security profile can subscribe to the newly created topic. To subscribe to a topic, the app calls subscribeToTopic() on ADM with the topic name. ADM notifies your app through the onSubscribe() or onSubscribeError() callback. Your app should override these callback methods defined in the com.amazon.device.messaging.ADMMessageHandlerJobBase and com.amazon.device.messaging.ADMMessageHandlerBase classes.

Subscribe example

To unsubscribe from a topic, the app calls ADM unsubscribeFromTopic() with the topic name. ADM notifies your app through the onUnsubscribe() or onUnsubscribeError() callback. Your app should override these callback methods defined in the com.amazon.device.messaging.ADMMessageHandlerJobBase and com.amazon.device.messaging.ADMMessageHandlerBase classes.

Unsubscribe example

These APIs might not be available on older Fire OS devices, which could cause apps on those devices to crash. To avoid this, use a try-catch block when calling these APIs as shown in the following example.

Callback method description

Callback methodDescription
onSubscribe()Called on successful subscription to a topic with parameters topic (topic the app is subscribed to) and application context.
onSubscribeError()Called when a subscription request fails with parameter topic (topic the app was trying to subscribe to), error ID, and application context.
onUnsubscribe()Called on successful unsubscription from a topic with parameter topic (topic the app is unsubscribed from), and application context.
onUnsubscribeError()Called when an unsubscription request fails with parameter topic (topic the app was trying to unsubscribe from), error ID, and application context.

Error ID and description

Error IDDescription
INVALID_MANIFESTManifest doesn’t have required permissions/broadcast receiver intent-filters defined. Check the integration steps and update the manifest file.
INTERNAL_ERRORInternal unhandled error similar to an HTTP 500 status code. No need to do anything.
INVALID_TOPICProvided topic is not valid. It should not be null and topic naming should follow this pattern [a-zA-Z0-9-_.~%]{1,100}.
NOT_REGISTERED_WITH_TBMApp is not registered for TBM. Register your app for Topic-Based Messaging.
UNREGISTEREDApp is not registered or registration ID is Invalid. Call ADM startRegister() to register again.
ALREADY_SUBSCRIBEDApp is already subscribed to the topic. Do not try to subscribe again.
NOT_SUBSCRIBEDApp is already unsubscribed, or the given topic does not exist. Do not try to unsubscribe from this topic.
MAXIMUM_SUBSCRIPTION_EXCEEDEDMaximum subscription limit exceeded means either of the following,
(i) your security profile is allocated with 100 topics
(ii) your app instance is subscribed to 100 topics
(iii) the topic is subscribed with 10,000 app instances (registration IDs).
TOO_MANY_REQUESTSToo many subscribe/unsubscribe requests. Retry after 30 seconds.
SERVICE_NOT_AVAILABLEUnable to communicate with the ADM service.

Sample code for callback methods

Receive and handle topic messages

ADM delivers messages to a topic in the same way it delivers to a single registration ID. See ADM Message Types for more information.

Send a message to topic

Prerequisites

To send a message to a topic, complete these prerequisites. After you meet these prerequisites, you can send a message to the topic with ADM programmatically.

Request format

To send a message to a topic, your server issues an HTTP POST request, as shown in the following example.
To get the complete POST URL, combine the second line (Host) and the first line (POST) as shown here.

Request requirements

The request itself consists of two parts: a header and a message body.

Header fields

The header must contain the following fields:
FieldDescriptionExample
AuthorizationInclude your current access token here. Value must be: Bearer (YOUR_ACCESS_TOKEN)Authorization: <Your access token>
Content-TypeValue must be: application/jsonContent-Type: application/json
X-Amzn-Type-VersionValue must be: com.amazon.device.messaging.ADMMessage@1.0X-Amzn-Type-Version: com.amazon.device.messaging.ADMMessage@1.0
AcceptValue must be: application/jsonAccept: application/json
X-Amzn-Accept-TypeValue must be: com.amazon.device.messaging.ADMSendResult@1.0X-Amzn-Accept-Type: com.amazon.device.messaging.ADMSendResult@1.0

Message body parameters

For message body content, provide a JSON object with a string containing the following parameters.
ParameterDescriptionExample
dataThe payload data to send with the message. The data must be in 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 (if not provided with the notification field in the message body). 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 the 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":{}.

If both data and notification payload are provided in the sent message, the combined total size can’t be greater than 6 KB.
"data":{ "from":"Sam", "message":"Hey, Max. How are you?", "time":"10/26/2012 09:10:00" }
notificationThe payload notification to send with the message. Notification messages require using predefined key-value pairs. Here are the key-value pairs supported by ADM notifications.

If the data and notification payload are provided in the message, the combined total size can’t be greater than 6 KB.
"notification":{"title":"ADM Message Notification","body":"We have a new offer for you!"}
priorityOptional value. There are two values for the sent message priority: normal and high priority. Normal is the default priority for messages. 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. The default value is normal."priority": "high"
consolidationKeyOptional 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"
expiresAfterOptional 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 1 (1 second) to 2678400 (31 days), inclusive. The default value is 604800 (1 week)."expiresAfter":86400
topicMandatory value. The topic to which your app instances are subscribed, and to which the message is to be sent. A string value should satisfy the regex pattern [a-zA-Z0-9-_.~%]{1,100}."topic":"SomeTopic"

Response format

After successfully receiving and interpreting your POST request message, ADM servers send an HTTP response message like the following.
ADM returns an HTTP 200 status code if it accepts the message and enqueues it for delivery to the device. For the 200 response code, the response message contains the following parameter in a JSON object:
  • messageId: An ID associated with the message sent, and the topic to which it is sent.
ADM returns an error (non-200) status code if it doesn’t accept the message. In this case, the response message might contain the following parameter in the body of the JSON object:
  • reason: The reason the request was not accepted.

ADM HTTP error status codes

The following table describes possible HTTP error status codes when sending a topic-based message with the ADM service.
HTTP status codeDescriptionExample
400In these scenarios, the request is rejected with a 400 response code.

1. The topic value does not satisfy the regex pattern [a-zA-Z0-9-_.~%]{1,100}.

2. The topic has no active subscriptions, meaning no registrationIds are subscribed to it.

3. An input parameter, besides the topic, is invalid such as:
- InvalidData - Neither the data nor notification field is provided.
- InvalidConsolidationKey - The length of the key is greater than 64.
- InvalidExpiration - The value is less than 1 or greater than 2678400.
- InvalidType - The typeVersion and acceptType values provided in the header are not allowed values.

4. The security profile identified by the access token is not registered with Topic-Based Messaging.
"reason": "Security profile amzn1.application.<32 hexadecimal characters> is not registered for TopicBasedMessaging."
401The 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"
413The message payload provided in the data parameter exceeded the maximum allowable data size (6 KB)."reason":"MessageTooLarge"
429The requester has exceeded their maximum allowable message rate. The sender can retry later according to the Retry-After header directions included in the response. To ensure high availability, ADM limits the number of messages sent over a given period of time. If you have specific capacity requirements, contact us and provide the following information:
- your name
- company name
- your email address
- requested TPS (transactions per second) limit
- reason
"reason":"MaxRateExceeded"
500There was an internal server error. The requester can retry later according to the Retry-After header directions included in the response.n/a
503The server is temporarily unavailable. The requester can try later according to the Retry-After header directions included in the response.n/a

Response header fields

FieldDescriptionExample
X-Amzn-RequestIdA 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: <Amazon RequestId>
Retry-AfterError responses with HTTP status codes of 429, 500, or 503 include this field. The Retry-After message specifies how long the service is expected to be unavailable. This value can be either a decimal number of seconds 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: 30
Content-TypeThe resource content type: application/jsonContent-Type: application/json

Send a message to a topic and handle the response

The following code sample demonstrates how your server software might send a message to a topic, and handle the ADM server response.
Last modified on February 13, 2026