Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Subscribing to Sync Objects

Sync for IoT is currently in Developer Preview, which means access is by invite only. If you'd like to try what you see in these docs, sign up for the developer preview and the team at Twilio will get you onboarded.

IoT devices (or indeed, any device that can run an MQTT client) can act as data sinks by subscribing to well-named MQTT topics that correspond with Sync objects. This lets you exchange data, deliver commands, or impress a desired state on a device from a web- or mobile-driven dashboard or control panel. This feature behaves identically across all existing Sync object types and their sub-resources.

Note: the addressed objects must be created before a subscription is attempted. The subscription will fail with an error (PUBACK with status code 0xff) in case the object with requested unique name or SID does not exist.

Documents

The topic mapping pattern for Sync Documents is sync/docs/{DocumentId}, where DocumentId is an existing Sync Document unique name or SID. Subscribing to a matching topic name enables receiving notifications about changes of the state of the document. Complete payload of an updated document shall be delivered per each notification.

The table below provides examples of subscribing to MQTT topics projected to Sync Document objects.

MQTT Topic Sync URL Behavior

sync/docs/myDoc

https://sync.twilio.com
/v1/Services/ISxx/Documents/myDoc

Subscribing to topic enables receiving state updates of the document with given unique name belonging to Sync service instance ISxx.

sync/docs/ETxx

https://sync.twilio.com
/v1/Services/ISxx/Documents/ETxx

Same as above, with Document object addressed by SID instead of unique name.

Note: the Sync document subscriber at QoS level 1 will automatically receive the latest snapshot of the subscribed document, i.e. the reflection of the current document state. The gateway shall also deliver both real-time state updates, and, upon network reconnection, the last known state if it’s different from the one that was last acknowledged by the client.

Lists

The topic mapping pattern for Sync Lists is sync/lists/{ListId}, where ListId is a unique name or SID of an existing Sync List object. Subscribing to a matching topic name enables receiving notifications about new items pushed to the list object. Complete payload of an added item shall be delivered per each notification.

In addition to the list "push" semantics, there is also an option to subscribe to updates of individual list items, with mapping pattern sync/lists/{ListId}/{ItemIndex}. Subscribing to such topic name enables receiving notifications about updates of an item state with the given ItemIndex. It is likewise possible to subscribe to updates of all items in the list using wildcards. Complete payload of an updated item shall be delivered per each notification.

The table below provides examples of subscribing to MQTT topics projected to Sync List objects.

MQTT Topic Sync URL Behavior

sync/lists/myList

https://sync.twilio.com
/v1/Services/ISxx/Lists/myList

Subscribing to topic enables receiving new items added to the list with given unique name belonging to Sync service instance ISxx.

sync/lists/ESxx

https://sync.twilio.com
/v1/Services/ISxx/Lists/myList

Same as above, with List object addressed by SID instead of unique name.

sync/lists/myList/42

https://sync.twilio.com
/v1/Services/ISxx/Lists/myList
/Items/42

Subscribing to topic enables receiving state updates of existing list item with given unique name and index 42.

sync/lists/ESxx/42

https://sync.twilio.com
/v1/Services/ISxx/Lists/ESxx
/Items/42

Same as above, with List object addressed by SID instead of unique name.

sync/lists/myList/#
sync/lists/myList/+

https://sync.twilio.com
/v1/Services/ISxx/Lists/myList
/Items (all contained items)

Subscribing to topic enables receiving state updates of any existing list item. Provided wildcards (#, +) comply to MQTT specification.

Payload is the updated data itself. Client can deduce item index from the message topic name.

sync/lists/ESxx/#
sync/lists/ESxx/+

https://sync.twilio.com
/v1/Services/ISxx/Lists/ESxx
/Items (all contained items)
Same as above, with List object addressed by SID instead of unique name.

Note: the Sync list subscriber at QoS level 1 that addresses individual items by index will automatically receive the latest snapshot of the subscribed item, i.e. the reflection of the current list item state. The gateway shall also deliver both real-time state updates, and, upon network reconnection, the last known item state if it's different from the one that was last acknowledged by the client.

Maps

The topic mapping pattern for Sync Maps is sync/maps/{MapId}, where MapId is a unique name or SID of an existing Sync Map object. Subscribing to such topic name enables receiving notifications about new items inserted into the map object. Complete payload of an updated map item shall be delivered per each notification.

In addition to map "insert" semantics, there is also an option to subscribe to updates of individual map items, with mapping pattern being sync/maps/{MapId}/{ItemKey}. Subscribing to such topic name enables receiving notifications about updates of an item state with the given ItemKey. It is likewise possible to subscribe to updates of all items in the map using wildcards. Complete payload of an updated item shall be delivered per each notification.

The table below provides examples of publishing to MQTT topics projected to Sync Map objects.

MQTT Topic Sync URL Behavior

sync/maps/myMap

https://sync.twilio.com
/v1/Services/ISxx/Maps/myMap

Subscribing to topic enables receiving new items inserted into the map with given unique name belonging to Sync service instance ISxx.

sync/maps/MPxx

https://sync.twilio.com
/v1/Services/ISxx/Maps/MPxx

Same as above, with Map object addressed by SID instead of unique name.

sync/maps/myMap/mykey

https://sync.twilio.com
/v1/Services/ISxx/Maps/myMap
/Items/myKey

Subscribing to topic enables receiving state updates of existing map item with given key.

sync/maps/MPxx/mykey

https://sync.twilio.com
/v1/Services/ISxx/Maps/MPxx
/Items/myKey

Same as above, with Map object addressed by SID instead of unique name.

sync/maps/myMap/#
sync/maps/myMap/+

https://sync.twilio.com
/v1/Services/ISxx/Maps/myMap
/Items (all contained items)

Subscribing to topic enables receiving state updates of any existing map item. Provided wildcards (#, +) comply to MQTT specification.

Payload is the updated data itself. Client can deduce key name from the message topic name.

sync/maps/MPxx/#
sync/maps/MPxx/+

https://sync.twilio.com
/v1/Services/ISxx/Maps/MPxx
/Items (all contained items)
Same as above, with Map object addressed by SID instead of unique name.

Note: the Sync map subscriber at QoS level 1 that addresses individual items by keys will automatically receive the latest snapshot of the subscribed item, i.e. the reflection of the current map item state. The gateway shall also deliver both real-time state updates, and, upon network reconnection, the last known item state if it's different from the one that was last acknowledged by the client.

Message Streams

The topic mapping pattern for Sync Message Streams is sync/streams/{StreamId}, where StreamId is an existing Sync Message Stream unique name or SID. Subscribing to a matching topic name enables receiving new messages posted to this message stream. Complete payload of a posted stream message shall be delivered per each notification.

The table below provides examples of subscribing to MQTT topics projected to Sync Message Stream objects.

MQTT Topic Sync URL Behavior

sync/streams/myStream

https://sync.twilio.com
/v1/Services/ISxx/Streams/myStream

Subscribing to topic enables receiving new messages posted to the stream with given unique name belonging to Sync service instance ISxx.

sync/streams/TOxx

https://sync.twilio.com
/v1/Services/ISxx/Streams/TOxx

Same as above, with Message Stream object addressed by SID instead of unique name.

Note: the Sync message stream subscriber at QoS level 1 will be accepted as QoS level 0 instead, as stream messages are not persisted. The gateway shall deliver only real-time messages, and all messages missed while subscriber being offline shall be discarded.

Caveats

The MQTT specification states that each subscription should be assigned a QoS. Since this is a foreign concept to Sync, we have assigned the following meaning to this parameter:

  • In case QoS 0 is requested by the subscriber, the subscriber shall only receive new real-time updates to documents, lists, maps or their sub-items as QoS 0 messages, ignoring all state updates that were made while the subscriber was offline.
  • For message streams: subscriptions are acknowledged as QoS 0 regardless of the requested QoS level. Sync does not keep history of messages, as they are ephemeral by design.
  • For documents, lists and maps: In case QoS 1 or QoS 2 is requested by the subscriber, QoS 1 subscription shall be acknowledged. Missed object state mutations, including updates and item insertions on the subscribed object shall be replayed to the subscriber shortly after reconnect, via QoS 1 messages. The gateway keeps track of the last successfully delivered event for each MQTT subscription. Missed updates shall be replayed by the gateway in sequence.
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.