Subscribing
To subscribe to a topic you'll first need your Application ID. This is the same value used to access the API and to authenticate with the MQTT service. The topic you subscribe to will depend on your access permissions and the data you want to receive.
If you have any issues with permissions and/or topics, please refer to MQTT Permissions.
Our topics are grouped the same way as our permissions. When subscribing you should use your Application ID followed by a forward slash and the topic group, as per your access permissions and what data you want to receive.
| Type | Topic |
|---|---|
| Devices | <application_id>/hubs/<hub_id> or #<application_id>/devices/<device_id> or # |
| Processes | <application_id>/processes/<process_id> or # |
| Documents | <application_id>/documents/<collection_id> or # |
Topics such as #, $SYS/#, are unavailable for subscription.
Devices & Hubs
The devices topic is used to subscribe to data from devices and hubs. This data could be used to monitor the status of devices such as
traffic lights, terminals, and weighbridges/scales. write permissions are also available for the device topic.
The topic structure for devices can be found in the Topic Structure article.
Processes
This documentation is still under construction and is not yet fully supported for subscribing.
Documents
The documents topic is used to subscribe to data indicating that changes have been made via our user interface or the API, to a collection within the application you are subscribed to.
This topic was designed to allow feedback to users if a document was modified by another user, device, 3rd party, or our API, if they had that document open or were editing it.
A secondary function has been to alleviate 3rd-party reliance on "timed synchronization" (synchronizing data every X seconds, or minutes).
Using this topic a 3rd-party can subscribe to all changes to all collections and receive updates as they happen.
The full document data is not included in the topic, so an API request to receive the data is then required. This is to reduce the amount of data sent over the MQTT service.
The topic structure for document events can be found in the Topic Structure article.