Server-sent events

A client can subscribe to SmartThings events using server-sent events (SSE). This allows the client to open a socket to receive events from SmartThings over HTTP.

An SSE subscription involves two steps:

SSE subscriptions use the HTTP/1.1 protocol. Connections are unidirectional and read-only. Data flows from server to client, and multiple SmartThings event types can be monitored via a single connection. For example, a browser client can use SSE to continuously update a slider that indicates radio volume or brightness level.

See the W3C specification for SSE.

Authorization

Clients can open one socket per user/token to receive subscriptions.

You must pass an OAuth token in the request header when calling the below API methods. When creating or updating a subscription, the required token scopes will depend on the types of subscriptions you wish to create (no OAuth scopes are required to get or delete subscriptions).

Example

Authorization: Bearer <token>

SSE API

Create the subscription

POST /subscriptions

This subscribes the client to events according to the specified filters.

Subscription filter Example Description
SMARTAPPIDS { "type": "SMARTAPPIDS", "value":["id1", "id2", "id3", …]} List of SmartApp IDs.
LOCATIONIDS { "type": "LOCATIONIDS", "value":["id1", "id2", "id3", …]}
{ "type": "LOCATIONIDS", "value":["ALL"]}
List of Location IDs. Specify "ALL" to indicate all Location IDs authorized on the token.
INSTALLEDSMARTAPPIDS { "type": "INSTALLEDSMARTAPPIDS", "value":["id1", "id2", "id3", …]} List of installed SmartApp IDs.
DEVICEIDS { "type": "DEVICEIDS", "value":["id1", "id2", "id3", …]} List of device IDs.

Example request

{
    "name": "my-subscription-name",
    "version": 1,
    "subscriptionFilters": [
       {
          "type": "LOCATIONIDS",
          "value": ["ALL"]
       }
    ]
  }

Example response

{
  "subscriptionId": "33c78a39-9145-4cd9-9b9e-4ae538111e94",
  "registrationUrl": "https://example.smartthings.com/sse",
  "version": 1,
  "name": "my-subscription-name",
  "subscriptionFilters": [
    {
      "type": "LOCATIONIDS"
    }
  ]
}

Make note of the registrationUrl. This will be used to establish the SSE connection.

Connect to the registration URL

GET <registrationURL>

Connect to the the registrationUrl you obtained above. Once the SSE connection is established, you receive a welcome event with the value "CONTROL_EVENT".

Example response (connection success)

event: CONTROL_EVENT
data: welcome

Your client will subsequently receive events as they occur. See the Event Types reference.

In the below example, a device event is sent when the device receives an "unlock" command.

Example response (device event)

...
event: DEVICE_EVENT
data: {
  "eventTime": 1536708654731,
  "eventType": "DEVICE_EVENT",
  "deviceEvent": {
    "eventId": "ba65aafb-b61a-11e8-9cc3-83b27408aa79",
    "locationId": "8b776d0a-46dc-4542-881b-ed130f0308f8",
    "deviceId": "adbd5544-d80e-4cdb-be2e-8fdc2e9162e5",
    "componentId": "main",
    "capability": "lock",
    "attribute": "lock",
    "value": "unlocked",
    "valueType": "string",
    "stateChange": true,
    "data": null,
    "subscriptionName": "locationSub"
    },
...
}

Get a subscription

GET /subscriptions/<subscriptionID>

This call returns a subscription. The subscription ID is a required URL query parameter.

The response is identical to the payload returned when creating a subscription.

Update a subscription

PUT /subscriptions/<subscriptionID>

This call is used to update the filters used in a subscription. The subscription ID is a required URL query parameter. See Create the subscription for a list of possible filters.

Example request

{
  "subscriptionFilters": [
    {
      "type": "SMARTAPPIDS"
    }
  ]
}

Example response

{
  "subscriptionId": "33c78a39-9145-4cd9-9b9e-4ae538111e94",
  "registrationUrl": "https://example.smartthings.com/sse",
  "version": 1,
  "name": "my-subscription-name",
  "subscriptionFilters": [
    {
      "type": "SMARTAPPIDS"
    }
  ]
}

Delete a subscription

DELETE /subscriptions/<subscriptionID>

This deletes a subscription. The subscription ID is a required URL query parameter.