Subscriptions
SmartApps may create subscriptions to events for authorized devices.
When the subscribed-to event occurs, your SmartApp will receive a POST
request with information about the triggering event.
For example, an app may wish to be notified when a configured motion sensor detects motion, when a light is turned on, or when a refrigerator door is opened.
A SmartApp creates subscriptions using the Subscriptions API.
#
Subscriptions API BasicsSubscriptions belong to a specific installed instance of a SmartApp. The Subscriptions API follows the path pattern of https://api.smartthings.com/installedapps/{installedAppId}/subscriptions
.
Subscriptions are typically created or updated during the INSTALL and UPDATE lifecycles, when the user has selected devices and granted the requested access to your SmartApp.
When a subscribed-to event occurs, your SmartApp will receive a POST
request containing information about the event, so your app can react accordingly.
See Subscription Event Handling for more information.
tip
Visit our API documentation to learn more about the Subscriptions API
#
Subscription TypesThere are two types of subscriptions that may be created:
- Subscriptions to specific devices authorized by the user ("Device subscriptions").
- Subscriptions to all devices in a user's Location for a specified Capability, if the user authorizes access to all devices ("Capability subscriptions").
#
Device SubscriptionsSmartApps may create subscriptions for specific devices selected and authorized by the user during configuration.
Device subscriptions are created by specifying "sourceType:": "DEVICE"
and including a "device"
object in the JSON request body:
#
Components, Capabilities, and AttributesDevice subscriptions may be created at the Component, Capability, and Attribute (and Attribute Value) granularity, or some combination thereof.
important
When subscribing to a specific Attribute Value, the value can be any valid JSON object type, and should correspond to the Attribute type defined by the Capability. For example, if an Attribute is of type NUMBER, then a JSON number would be used.
When receiving device events, the type of the value will also correspond to the Attribute type defined in the Capability, as noted above.
At its most granular, subscriptions can be created for a specific value of an Attribute of a specified Capability, on a specific Component. The following shows a subscription request body for when a switch
Capability device, of the main
component, has its switch
Attribute change to on
:
Use the wildcard operator *
to specify any value. The following example subscription creation request body demonstrates creating a subscription to a device for any Capability and Attribute Event:
Omitting the value
is equivalent to specifying all values.
#
Required PermissionsCreating a device subscription requires that the SmartApp has requested the permission to read specific authorized devices. This is set during app creation or update. The permission format is r:devices:*
.
The SmartApp does not need to request any additional permissions during the INITIALIZE phase of the CONFIGURE lifecycle.
Upon selection of devices and authorization by the user to read these devices, all incoming requests to your SmartApp will contain permission in the form of "r:devices:<device-id>"
.
This permission allows your app to get information (including device attribute values) about the authorized device.
#
Capability SubscriptionsSmartApps may also create subscriptions for all devices of a specified Capability in a user's Location, if the user authorized the app to read all devices in their Location.
Capability subscriptions are created by specifying "sourceType:": "CAPABILITY"
and including a "capability"
object in the JSON request body:
In the example above, a subscription is created for all contact sensors in the user's Location. Any removal or addition of devices in the user's Location will also be accounted for in the subscription without your app needing to do anything.
#
Required PermissionsCreating a Capability subscription requires that the SmartApp has requested the read all devices permission. This is set during app creation or update. The permission format is r:devices
.
The SmartApp also needs to request the r:devices
permission during the INITIALIZE phase of the CONFIGURE lifecycle:
The user will be prompted to grant your app permission to read all devices in their Location.
#
Subscription Event HandlingWhen a subscribed-to event occurs, your SmartApp will be called with an EVENT lifecycle phase, and an Event data object containing information about the triggering event:
#
Deleting SubscriptionsIndividual subscriptions can be deleted by issuing a DELETE request to the /installedapps/{installedAppId}/subscriptions/{subscriptionId}
endpoint:
All subscriptions for an installed app can be deleted by issuing a DELETE request to the /installedapps/{installedAppId}/subscriptions
endpoint:
#
Handling Updated User ConfigurationsOnce a user installs your SmartApp, they may later reconfigure it to select different devices. If any of these devices have been previously subscribed-to, your app needs to account for this by deleting subscriptions to devices no longer configured, and creating new subscriptions for newly configured devices.
#
Subscription Examples#
Device SubscriptionThe following example shows creating a subscription to the "open" attribute of a contact sensor, including the necessary permissions requested during configuration.
It also demonstrates handling the UPDATE lifecycle, when a user may change configured devices. In this case, our app needs to delete subscriptions for devices that are no longer authorized, and create new subscriptions for newly configured devices. For simplicity, our app will delete all existing subscriptions and create a new subscription, regardless of whether the device configuration has changed.
#
Capability SubscriptionThe following example shows creating a subscription to the contact
attribute, monitoring for a state change of all contact sensors for the user's Location, including the necessary permissions requested during configuration.
In this case, there is no need to handle the UPDATE lifecycle, since the user has agreed to authorize your app to read information about all devices in their Location: