AWS IoT
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Topics

The message broker uses topics to route messages from publishing clients to subscribing clients. Topics are UTF-8 encoded heirarchical strings. The forward slash (/) is used to separate levels in the topic hierarchy. For example:

Sensor/temperature/room1

This topic refers to a temperature sensor in room 1.

Note

Do not use personally identifiable information in your topics.

The following table lists the wildcards that can be used in the topic filter when you subscribe.

Topic Wildcards

Wildcard Description
#

Must be the last character in the topic to which you are subscribing. Works as a wildcard by matching the current tree and all subtrees. For example, a subscription to Sensor/# receives messages published to Sensor/, Sensor/temp, Sensor/temp/room1, but not the messages published to Sensor.

+

Matches exactly one item in the topic hierarchy. For example, a subscription to Sensor/+/room1 receives messages published to Sensor/temp/room1, Sensor/moisture/room1, and so on.

The topic namespace is isolated for each AWS account and region pair. For example, the Sensor/temp/room1 topic for an AWS account is independent from the Sensor/temp/room1 topic for another AWS account. This is true of regions, too. The Sensor/temp/room1 topic in the same AWS account in us-east-1 is independent from the same topic in us-east-2. AWS IoT does not support sending and receiving messages across AWS accounts and regions.

Reserved Topics

Except for those topics listed here, any topics beginning with $ are considered reserved and are not supported for publishing and subscribing. Any attempts to publish or subscribe to topics beginning with $ result in a terminated connection.

Event Topics

Topic Allowed Operations Description

$aws/events/presence/connected/clientId

Subscribe

AWS IoT publishes to this topic when an MQTT client with the specified client ID connects to AWS IoT. For more information, see Connect/Disconnect Events.

$aws/events/presence/disconnected/clientId

Subscribe

AWS IoT publishes to this topic when an MQTT client with the specified client ID disconnects to AWS IoT. For more information, see Connect/Disconnect Events.

$aws/events/subscriptions/subscribed/clientId

Subscribe

AWS IoT publishes to this topic when an MQTT client with the specified client ID subscribes to an MQTT topic. For more information, see Subscribe/Unsubscribe Events.

$aws/events/subscriptions/unsubscribed/clientId

Subscribe

AWS IoT publishes to this topic when an MQTT client with the specified client ID unsubscribes to an MQTT topic. For more information, see Subscribe/Unsubscribe Events.

Rule Topics

Topic Allowed Operations Description

$aws/rules/ruleName

Publish

A device or an application publishes to this topic to trigger rules directly. For more information, see Basic Ingest.

Thing Shadow Topics

Topic Allowed Operations Description

$aws/things/<thingName>/shadow/delete

Publish/Subscribe

A device or an application publishes to this topic to delete a shadow. For more information, see /delete.

$aws/things/<thingName>/shadow/delete/accepted

Subscribe

The Device Shadow service sends messages to this topic when a shadow is deleted. For more information, see /delete/accepted.

$aws/things/<thingName>/shadow/delete/rejected

Subscribe

The Device Shadow service sends messages to this topic when a request to delete a shadow is rejected. For more information, see /delete/rejected.

$aws/things/<thingName>/shadow/get

Publish/Subscribe

An application or a thing publishes an empty message to this topic to get a shadow. For more information, see Shadow MQTT Topics.

$aws/things/<thingName>/shadow/get/accepted

Subscribe

The Device Shadow service sends messages to this topic when a request for a shadow is made successfully. For more information, see /get/accepted.

$aws/things/<thingName>/shadow/get/rejected

Subscribe

The Device Shadow service sends messages to this topic when a request for a shadow is rejected. For more information, see /get/rejected.

$aws/things/<thingName>/shadow/update

Publish/Subscribe

A thing or application publishes to this topic to update a shadow. For more information, see /update.

$aws/things/<thingName>/shadow/update/accepted

Subscribe

The Device Shadow service sends messages to this topic when an update is successfully made to a shadow. For more information, see /update/accepted.

$aws/things/<thingName>/shadow/update/rejected

Subscribe

The Device Shadow service sends messages to this topic when an update to a shadow is rejected. For more information, see /update/rejected.

$aws/things/<thingName>/shadow/update/delta

Subscribe

The Device Shadow service sends messages to this topic when a difference is detected between the reported and desired sections of a shadow. For more information, see /update/delta.

$aws/things/<thingName>/shadow/update/documents

Subscribe

AWS IoT publishes a state document to this topic whenever an update to the shadow is successfully performed. For more information, see /update/documents.

Job Topics

Topic Allowed Operations Description

$aws/things/<thingName>/jobs/get

Publish

Devices publish a message to this topic to make a GetPendingJobExecutions request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/get/accepted

Subscribe

Devices subscribe to this topic to receive successful responses from a GetPendingJobExecutions request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/get/accepted

Subscribe

Devices subscribe to this topic to receive successful responses to a GetPendingJobExecutions request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/start-next

Publish

Devices publish a message to this topic to make a StartNextPendingJobExecution request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/start-next/accepted

Subscribe

Devices subscribe to this topic to receive successful responses to a StartNextPendingJobExecution request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/start-next/rejected

Subscribe

Devices subscribe to this topic to receive successful responses to a StartNextPendingJobExecution. request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/jobId/get

Publish

Devices publish a message to this topic to make a DescribeJobExecution request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/<jobId>/get/accepted

Subscribe

Devices subscribe to this topic to receive successful responses to a DescribeJobExecution request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/<jobId>/get/rejected

Subscribe

Devices subscribe to this topic to receive successful responses to a DescribeJobExecution request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/<jobId>/update

Publish

Devices publish a message to this topic to make a UpdateJobExecution request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/<jobId>/update/accepted

Subscribe

Devices subscribe to this topic to receive successful responses to a UpdateJobExecution request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/<jobId>/update/rejected

Subscribe

Devices subscribe to this topic to receive successful responses to a UpdateJobExecution request. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/notify

Subscribe

Devices subscribe to this topic to receive notifications when a job execution is added or removed to the list of pending executions for a thing. For more information, see Using the AWS IoT Jobs APIs.

$aws/things/<thingName>/jobs/notify-next

Subscribe

Devices subscribe to this topic to receive notifications when the next pending job execution for the thing is changed. For more information, see Using the AWS IoT Jobs APIs.

$aws/events/job/<jobId>/completed

Subscribe

The Jobs service publishes an event on this topic when a job completes. For more information see: Job Events.

$aws/events/job/<jobId>/canceled

Subscribe

The Jobs service publishes an event on this topic when a job is canceled. For more information see: Job Events.

$aws/events/job/<jobId>/deleted

Subscribe

The Jobs service publishes an event on this topic when a job is deleted. For more information see: Job Events.

$aws/events/job/<jobId>/cancellation_in_progress

Subscribe

The Jobs service publishes an event on this topic when a job cancellation begins. For more information see: Job Events.

$aws/events/job/<jobId>/deletion_in_progress

Subscribe

The Jobs service publishes an event on this topic when a job deletion begins. For more information see: Job Events.

$aws/events/jobExecution/<jobId>/succeeded

Subscribe

The Jobs service publishes an event on this topic when job execution succeeds. For more information see: Job Events.

$aws/events/jobExecution/<jobId>/failed

Subscribe

The Jobs service publishes an event on this topic when a job execution fails. For more information see: Job Events.

$aws/events/jobExecution/<jobId>/rejected

Subscribe

The Jobs service publishes an event on this topic when a job execution is rejected. For more information see: Job Events.

$aws/events/jobExecution/<jobId>/canceled

Subscribe

The Jobs service publishes an event on this topic when a job execution is canceled. For more information see: Job Events.

$aws/events/jobExecution/<jobId>/timed_out

Subscribe

The Jobs service publishes an event on this topic when a job execution times out. For more information see: Job Events.

$aws/events/jobExecution/<jobId>/removed

Subscribe

The Jobs service publishes an event on this topic when a job execution is removed. For more information see: Job Events.

$aws/events/jobExecution/<jobId>/deleted

Subscribe

The Jobs service publishes an event on this topic when a job execution is deleted. For more information see: Job Events.

On this page: