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 Basics
Subscriptions belong to a specific installed instance of a SmartApp. The Subscriptions API follows the path pattern of
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.
Visit our API documentation to learn more about the Subscriptions API
There 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").
SmartApps 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 Attributes
Device subscriptions may be created at the Component, Capability, and Attribute (and Attribute Value) granularity, or some combination thereof.
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
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:
value is equivalent to specifying all values.
Creating 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
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
This permission allows your app to get information (including device attribute values) about the authorized device.
SmartApps 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.
Creating 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
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 Handling
When 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:
Individual subscriptions can be deleted by issuing a DELETE request to the
All subscriptions for an installed app can be deleted by issuing a DELETE request to the
#Handling Updated User Configurations
Once 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.
The 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.
The 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: