Skip to content

Subscriptions

Jump to bottom
Michelle Staley edited this page Jan 18, 2023 · 4 revisions

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.

Functions

Note: The list of functions can be found here.

  • list - Returns a list of all the subscriptions for an installed app. Optional the installedAppId UUID of the installed app.

  • get - Gets the definition of a specific subscription for the specified installed app. Requires name, the alphanumeric name of the subscription. Optional the installedAppId UUID of the installed app.

  • create - Creates a subscription for an installed app instance. Requires the data definition of the subscription. Optional the installedAppId UUID of the installed app.

  • delete - Deletes one or more subscriptions of an installed app. Requires name, the the name of the subscription to be deleted. If not specified, all the subscriptions associated with the installed app instance are deleted. Optional the installedAppId UUID of the installed app.

  • update - Updates a subscription. Requires name, the alphanumeric for the subscription name. Requires data, the new subscription definition. Optional the installedAppId UUID of the installed app.

  • subscribeToDevices - Creates device event subscriptions for one or more devices specified in a SmartApp device configuration setting. This method is intended for use from SmartApps or API Access apps and must be called from a client configured with an installedAppId. Use the create method if the client is not so configured. Requires devices, a SmartApp device configuration setting with one or more devices. Requires capability, the alphanumeric ID of the capability to subscribe to or '' to subscribed to all capabilities of the devices. Requires attribute string defining what attribute(s) and attribute value(s) to subscribe to. Specifying an attribute name such as 'switch' subscribed to all values of the switch attribute. Specifying a name.value string such as 'switch.on' subscribed to only the on values of the switch. Specifying the wildcard '' subscribes to all values of all attributes of the capability. Requires subscriptionName, the alphanumeric subscription name. Optional options map of options. If not stateChangeOnly is not specified the default is true. If modes is not specified then events are sent for all modes.

  • subscribeToCapability - Creates a device subscription to a specific capability for all devices in a location. This method is intended for use from SmartApps or API access apps and must be called from the client configured with an installedAppId and locationId. Use the create method if the client is not so configured. Requires capability, an alphanumeric ID for the capability. Requires attribute string defining what attribute(s) and attribute value(s) to subscribe to. attribute string defining what attribute(s) and attribute value(s) to subscribe to. Specifying an attribute name such as 'switch' subscribed to all values of the switch attribute. Specifying a name.value string such as 'switch.on' subscribed to only the on values of the switch. Specifying the wildcard '*' subscribes to all values of all attributes of the capability. Requires subscriptionName, the alphanumeric subscription name. Optional options map of options. If not stateChangeOnly is not specified the default is true. If modes is not specified then events are sent for all modes.

  • subscribeToModeChange - Subscribe to the mode change events from a location. This method is intended for use from SmartApps or API Access apps and must be called from a client configured with an installedAppId. Use the create method if the client is not so configured. Requires subscriptionName, an alphanumeric for the subscription name.

  • subscribeToDeviceLifecycle - Subscribes to device lifecycle events (i.e. create, update, and delete) from a location. This method is intended for use from SmartApps or API Access apps and must be called from a client configured with an installedAppId and locationId. Use the create method if the client is not so configured. Requires subscriptionName, an alphanumeric for the subscription name.

  • subscribeToDeviceHealth - Subscribes to devices health events (i.e. online and offline) from a location. This method is intended for use from SmartApps or API Access apps and must be called from a client configured with an installedAppId and locationId. Use the create method if the client is not so configured. Requires subscriptionName, an alphanumeric for the subscription name.

  • subscribeToSecuritySystem - Subscribes to security system events for a location. This method is intended for use from SmartApps or API Access apps and must be called from a client configured with an installedAppId and locationId. Use the create method if the client is not so configured. Requires subscriptionName, an alphanumeric for the subscription name.

  • subscribeToHubHealth - Subscribes to hub health events from a location. This method is intended for use from SmartApps or API Access apps and must be called from a client configured with an installedAppId and locationId. Use the create method if the client is not so configured. Requires subscriptionName, an alphanumeric for the subscription name.

  • subscribeToSceneLifecycle - Subscribes to scene lifecycle events from a location. This method is intended for use from SmartApps or API Access apps and must be called from a client configured with an installedAppId and locationId. Use the create method if the client is not so configured. Requires subscriptionName, an alphanumeric for the subscription name.

Deprecated Functions

  • unsubscribe - Deletes a subscription of an installed app. Requires name, the name of the subscription to delete. If not specified, then all subscriptions associated with the installed app instance are deleted. Use Delete instead

  • unsubscribeAll - Deletes all subscriptions on an installed app. Optional the installedAppId UUID of the installed app. Use Delete instead.

Clone this wiki locally