Real-Time Device Updates¶

This documentation describes how SmartHQ can notify your app of device changes in real time and corresponds to the Event Stream API.

Overview¶

SmartHQ can communicate real-time updates (events) and state information to your app without you having to poll the Digital Twin API. You define the types of events you want to receive—such as alerts, presence changes (online/offline status), service updates, and command outcomes—and SmartHQ continuously delivers them to your application as they occur.

There are two delivery channels that messages are sent over:

	WebSocket Delivery	HTTPS / SNS Callback Delivery
What is it?	A client-initiated, real-time connection used to configure event preferences and receive event updates from SmartHQ.	A cloud-managed, push-based delivery mechanism (via HTTPS POST or AWS SNS) used to configure event preferences and receive event updates from SmartHQ.
Connection type	WebSocket connection (wss://) maintained with keep-alive pings. The WebSocket URL can be retrieved from GET /v2/websocket (Digital Twin API).	SmartHQ sends event data via outbound HTTPS POST requests or SNS messages to the callback URL you registered with us.
How is it configured?	You send event configuration messages over the WebSocket connection telling SmartHQ what you want to be notified about. SmartHQ sends those events over the same WebSocket connection as they happen.	You send event configuration messages via the Digital Twin API (POST /v2/pubsub) telling SmartHQ what you want to be notified about. SmartHQ sends those events over the HTTPS / SNS Callback you registered with us.
Lifetime	The WebSocket connection lasts as long as the access token is valid. The access token's lifespan is 1 hour.	Always active as long as the callback is registered.
Best for	Real-time UIs, mobile apps, and web browsers	Backend systems, webhook handlers, cloud-to-cloud integrations

Message Types:

Type	Description	Applies to
Event Configuration Messages	JSON payloads your app sends to specify which event types to receive from SmartHQ (e.g., alerts, presence, commands).	• WebSockets • HTTPS / SNS callback
Event Messages	JSON payloads SmartHQ sends when the specified event occurs. The message format is the same across delivery methods.	• WebSockets • HTTPS / SNS callback

Clarification on Delivery Channel Overlap

WebSocket event configuration messages have no effect on HTTPS/SNS preferences.
HTTPS/SNS event configuration messages have no effect on WebSocket preferences.
You can implement either channel independently.

What is Pubsub?¶

"Pubsub" (publish-subscribe) is another way to refer to your app sending event configurations so that your app can receive events from SmartHQ.

Pubsub is the messaging pattern SmartHQ uses internally. You'll see pubsub in various field names and values throughout the API:

The Pubsub Endpoints are used to set event configurations for HTTPS / SNS Callbacks.
Pubsub is also a value for a field in the WebSocket's event configuration message.

Terminology Clarification

For clarity and to be consistent with current version of the AsyncAPI spec used for the Event Stream API, this documentation uses the terms "Event Configuration Messages" and "Event Messages" for clarity, but SmartHQ's internal implementation uses "pubsub" terminology, which is why you will see it in various places in the API and documentation.

WebSockets¶

One of the two delivery channels for real-time updates. You create a WebSocket connection with SmartHQ over which you can send JSON payloads to specify what events you want SmartHQ to notify you about, and SmartHQ will send those events to you as they happen in real time.

WebSocket Use Case Clarification

The only messages your app can send to SmartHQ over the WebSocket are Event Configuration Messages, which configure account-level and device-level event messages you want to receive. To send commands to devices or make other Digital Twin API requests, you must call the Digital Twin API over HTTPS — these operations cannot be performed over the WebSocket.

Endpoint¶

Your application must connect to the appropriate WebSocket endpoint for the user. GET /v2/websocket (Digital Twin API) returns the WebSocket URL. Your application can then connect to the WebSocket for as long as the access token is valid.

Request:

GET /v2/websocket HTTP/1.1
Host: client.mysmarthq.com
Authorization: Bearer 1/<access-token>

Response:

{
  "kind": "websocket#endpoint",
  "endpoint": "wss://example.com?access_token=randomvalue"
}

This WebSocket URL above must be re-retrieved each time you go to establish a WebSocket connection as the URL returned by GET /v2/websocket is subject to change and is not the same for every user.

Connecting¶

The access token is provided as part of the endpoint and is used to authenticate the connection. If the access token is invalid or the wrong endpoint is used, the connection request will be rejected.

SmartHQ will close the WebSocket connection when the access token expires. Your application can request a new access token and will be required to call GET /v2/websocket again to get a new WebSocket URL, reconnect, and resend event configuration messages.

Each WebSocket is a connection between your app and a single SmartHQ user, whose access token you used to make the GET /v2/websocket request. If maintaining many WebSockets is a concern, you can instead use the HTTPS/SNS callback delivery channel in which you still send the event configuration messages to SmartHQ for each user, but SmartHQ pushes all events to your single HTTPS endpoint or SNS topic, and you don't have to manage a bunch of live sockets.

Once you have the WebSocket URL from the GET /v2/websocket response, use your WebSocket client of choice (e.g. browser WebSocket, Node.js ws package) to open a connection.

Upon a successful connection, your app will receive the following payload.

{
  "kind":"websocket#connect",
  "success":true
}

Tip

It is recommended, but not required, to wait until the connection response is received before sending event configuration messages.

Ping & Pong¶

In order to keep connections alive and test a connection, a ping payload is provided. The optional id parameter can be used to correlate the request and response payloads.

{
  "kind": "websocket#ping",
  "action":"ping",
  "id":"abc123"
}

A response pong payload will be returned for each ping.

{
  "kind":"websocket#pong",
  "id":"abc123"
}

Ping Frequency

A ping request is suggested to be sent over the connection if there has been no other activity for 60 seconds.

It is not recommended to send pings more frequently or if other payloads have been sent or received within that window.

Limits¶

Idle WebSocket connections will be terminated after 10 minutes.

Individual JSON payloads sent over the WebSocket are limited to 32 KB.

Next Steps¶

Once you have connected to the WebSocket, you can send event configuration messages and begin to receive real-time updates. See the Message Types section below.

One of the two delivery channels for real-time updates. SmartHQ supports delivering real-time event messages over either HTTPS POST callbacks or AWS SNS topics. This is ideal for server-side integrations that cannot maintain a persistent WebSocket connection. This method is often used to send real-time updates to backend applications.

Registering a Callback Endpoint¶

To use HTTPS or SNS callback delivery, your application must have a callback URL or SNS topic pre-registered with SmartHQ.

How to Register

As of today, this configuration must be done by a SmartHQ Cloud Engineer. Developers should contact us to provide their callback URL(s) and request setup.

The callback URL mentioned here is not the same as your OAuth 2.0 Callback URL — they serve different purposes.

Configuring Event Messages¶

To choose which event types to receive—such as alerts, presence updates, and command outcomes—your app sends Event Configuration Messages to SmartHQ using the Digital Twin API (POST /v2/pubsub). See Event Configuration Messages below for payload details and What is Pubsub? to learn more about that.

Event Configuration Messages can target either the user's account or specific devices to define exactly which Event Messages SmartHQ will deliver to your HTTPS/SNS callback.

Configuration Persistence

For HTTPS/SNS callbacks, Account-Level Configuration and Device-Level Configuration persist indefinitely and are not tied to a single access token as in WebSockets.

Note: WebSocket and HTTPS/SNS preferences are independent—updating one doesn't affect the other.

Event Delivery¶

Your app does not initiate a connection like it would with WebSockets. Instead, SmartHQ pushes events to your registered endpoint(s) whenever a configured event occurs.

Callbacks are sent as:

HTTPS POST requests to your configured URL
SNS messages to your configured AWS topic

No session management required

Unlike WebSockets, callback delivery requires no token renewal, keep-alives, or session handling. Once configured, delivery is continuous.

Message Types¶

To receive real time updates for device state, alerts, etc., your app must tell SmartHQ what you want to be notified about.

The following message payload can be sent over either delivery channel: WebSockets or HTTPS / SNS Callbacks. You can choose which specific resources to configure that is appropriate to your use case.

Event configurations can be updated at any point in time.

Message Type	Direction	Purpose
Event Configuration Messages	App → SmartHQ	Configure which event types to receive at account/device level
Event Messages	SmartHQ → App	SmartHQ delivers real-time updates (e.g. alerts, presence, service state)

Event Configuration Messages¶

There are two types of event configuration messages your app sends to tell SmartHQ what events to send back as they happen: account-level and device-level configuration requests.

Once the delivery channel has been successfully set up and event configuration messages are sent, nothing additional is needed to receive updates from SmartHQ.

Conceptualizing Event Configuration Messages

This pseudocode shows how SmartHQ decides whether to deliver an event payload to your application based on the account-level and device-level preferences you've configured.

Pseudocode

  if (account-level.pubsub == true
    && (account-level.services == true || device-level.services == true)
  ) {
    deliverServiceEventToApp();
  }

This applies to presence, alerts, and commands as shown below.

Tip: See 'What is Pubsub?' to learn about that concept.

Account-Level Configuration Request

Configures which events to receive at the account level for a particular user the connection is established for.

Name	Type	Description
kind	string	Event delivery channel type (pubsub refers to the publish-subscribe messaging pattern used internally). Either `websocket#pubsub` (WebSocket) or `user#pubsub` (HTTPS/SNS callbacks)
action	string	(only include this field for WebSocket payloads) Must be `pubsub` when used ("pubsub" is used for internal routing).
pubsub	bool	Enables events for the account. Also notifies when new devices are added. Must be set to `true` to receive device specific updates.
services	bool	(optional) Enables receiving device and service events to be sent for all devices of a SmartHQ user. (Defaults to `false` if not specified.)
presence	bool	(optional) Enables online/offline status events for all devices of a SmartHQ user. (Defaults to `false` if not specified.)
alerts	bool	(optional) Enables alert notifications for all devices of a SmartHQ user. (Defaults to `false` if not specified.)
commands	bool	(optional) Enables command-outcome events for all devices of a SmartHQ user. Outcomes are only sent to the application which issued the command. (Defaults to `false` if not specified.)

WebSocket ExampleHTTPS / SNS Callbacks Example

Request:

This payload is sent over the WebSocket directly:

{
  "kind": "websocket#pubsub",
  "action": "pubsub",
  "pubsub": true,
  "services": true,
  "presence": false,
  "alerts": true,
  "commands": true
}

Response:

Upon successfully configuring preferences, the following response will be given. However, this only indicates the payload was accepted.

{
  "kind":"websocket#pubsub",
  "success": true
}

Request:

The POST /v2/pubsub endpoint of the Digital Twin API is called with the following request body:

{
  "kind": "user#pubsub",
  "pubsub": true,
  "services": true,
  "presence": false,
  "alerts": false,
  "commands": false
}

Response:

{
  "kind": "user#pubsub",
  "success": true
}

Device-Level Configuration Request

Configures which events to receive for a specific device.

Important Note

In order to configure device-level events, first configure the Account-Level events (see above) with the pubsub attribute value set to true.

Name	Type	Description
kind	string	Event delivery channel type (pubsub refers to the publish-subscribe messaging pattern used internally). Either `websocket#pubsub` (WebSocket) or `user#pubsub` (HTTPS/SNS callbacks)
action	string	(only include this field for WebSocket payloads) Must be `pubsub` when used ("pubsub" is used for internal routing).
deviceId	string	The unique ID of the device from which to receive events
services	bool	(optional) Enables receiving device and service events for this device. (Defaults to `false` if not specified.)
presence	bool	(optional) Enables receiving online/offline status events for this device. (Defaults to `false` if not specified.)
alerts	bool	(optional) Enables receiving alert notifications for this device. (Defaults to `false` if not specified.)
commands	bool	(optional) Enables receiving command-outcome events for this device. Outcomes are only sent to the application which issued the command. (Defaults to `false` if not specified.)

WebSocket ExampleHTTPS / SNS Callbacks Example

Request:

This payload is sent over the WebSocket directly:

{
  "kind": "websocket#pubsub",
  "action": "pubsub",
  "deviceId": "2108dfb5de62989a44925470e9c6824b9aaaf1fe966c39803042524892816b4d",
  "services": true,
  "presence": false,
  "alerts": true,
  "commands": true
}

Response:

Upon successfully configuring the event preferences, the following response will be given. However, this only indicates the payload was accepted.

{
  "kind":"websocket#pubsub",
  "success": true
}

Request:

The POST /v2/device/{deviceId}/pubsub endpoint of the Digital Twin API is called with the following request body (endpoint coming soon):

{
  "kind": "device#pubsub",
  "services": true,
  "presence": false,
  "alerts": false,
  "commands": false
}

Response:

{
  "kind": "device#pubsub",
  "success": true
}

Event Messages¶

These are the event messages SmartHQ sends to your application when any of the following changes (assuming you set these preferences): device configuration, device presence, service state changes, alert events, and command outcomes. The following are example messages your app can receive from SmartHQ.

Device Message

When a device is added, modified, or removed, your app that has configured account-level events will be notified. Your app is not able to selectively choose what devices or device configuration updates they will be notified of, the configuration is a single overall switch. The policies attached to a client will be used to filter information that is not authorized for view. The userId attribute is not included for WebSocket connections.

Example

{
  "kind": "pubsub#device",
  "userId": "abcdefghijklmno",
  "deviceId": "500e47f3f902dcb3bab5c464aa48e6dd872f59c91f1b67b3fc628ecefa838fcb",
  "adapterId": "4627a71238c040e71c92f59bec0097d7c98ab603",
  "gatewayId": "aff54d44524ef1e5f6fb61c549bcad0307223c2e47848c7a8a9d3f45f027ac9d",
  "deviceType": "cloud.smarthq.device.airconditioner",
  "lastSyncTime": "2019-05-21T15:38:53.448Z",
  "event": "created",
  "services": [
    {
      "serviceType": "cloud.smarthq.service.toggle",
      "domainType": "cloud.smarthq.domain.power",
      "serviceDeviceType": "cloud.smarthq.device.airconditioner",
      "serviceId": "9686818be9c62a71f32969c3416dfc7cc418b09efe7799a9d152d25c36e2f1ca",
      "config": {},
      "supportedCommands": [
        "cloud.smarthq.command.toggle.set"
      ]
    }
  ],
}

For device event messages, an event attribute is included with the payload to indicate whether the device was added or removed, or if the configuration was updated.

Presence Message

When a device presence changes from online to offline (or vice versa), the presence message is provided. The userId attribute is not included for WebSocket connections.

Example

{
  "kind": "pubsub#presence",
  "userId": "abcdefghijklmno",
  "deviceId": "500e47f3f902dcb3bab5c464aa48e6dd872f59c91f1b67b3fc628ecefa838fcb",
  "adapterId": "4627a71238c040e71c92f59bec0097d7c98ab603",
  "deviceType": "cloud.smarthq.device.airconditioner",
  "lastSyncTime": "2019-05-21T19:05:11.000Z",
  "presence": "ONLINE"
}

Service Message

When the state of a service changes. The userId attribute is not included for WebSocket connections.

Example

{
  "kind": "pubsub#service",
  "userId": "abcdefghijklmno",
  "deviceId": "500e47f3f902dcb3bab5c464aa48e6dd872f59c91f1b67b3fc628ecefa838fcb",
  "adapterId": "4627a71238c040e71c92f59bec0097d7c98ab603",
  "deviceType": "cloud.smarthq.device.airconditioner",
  "serviceId": "9686818be9c62a71f32969c3416dfc7cc418b09efe7799a9d152d25c36e2f1ca",
  "serviceType": "cloud.smarthq.service.toggle",
  "domainType": "cloud.smarthq.domain.power",
  "serviceDeviceType": "cloud.smarthq.device.airconditioner",
  "lastSyncTime": "2019-05-17T17:33:09.224Z",
  "lastStateTime": "2019-05-17T17:53:19.456Z",
  "config": {},
  "state": {
    "on": true
  },
  "statePrevious": {
    "on": false
  }
}

Alert Message

When a device triggers an alert with a service state update.

Example

{
    "kind": "pubsub#alert",
    "userId": "abcdefghijklmno",
    "deviceId": "6fda796068ed6b51580413ab989670673b77212edc965cf071ccdfb7f34f44ce",
    "adapterId": "e06293876c71165d197a6fe5ce25efe4bcc84780",
    "deviceType": "cloud.smarthq.device.fan",
    "alertType": "cloud.smarthq.alert.filterdirty",
    "lastAlertTime": "2021-02-26T14:07:23.354Z",
    "alertId": "ad04b0ea0455fb35e31b131a287c5e95097a26bc4f512406c0f19d9f13376cab",
    "services": [{
        "serviceType": "cloud.smarthq.service.mode",
        "domainType": "cloud.smarthq.domain.speed",
        "state": {
            "mode": "cloud.smarthq.type.mode.low"
        },
        "serviceId": "02be45a3c3f0bf605a07793a6a90258b26cd65422993f962360c5d60f90dab97",
        "serviceDeviceType": "cloud.smarthq.device.fan",
        "config": {
            "ordered": false,
            "supportedModes": ["cloud.smarthq.type.mode.high", "cloud.smarthq.type.mode.low", "cloud.smarthq.type.mode.medium", "cloud.smarthq.type.mode.off"]
        },
        "lastStateTime": "2021-02-26T14:07:23.354Z"
    }]
}

Command Message

When the outcome for a command was received.

Example

{
    "kind": "pubsub#command",
    "userId": "rt9e83niwhgp2s2",
    "deviceId": "c80f0c48601eeee43cefce99112db9c25dbab80a5bccd7abe09e8e276059e8e7",
    "adapterId": "4627a71238c040e71c92f59bec0097d7c98ab603",
    "deviceType": "cloud.smarthq.device.refrigerator",
    "serviceId": "1c07f611cd78c6e3c892eca69991f92fc9f9254ac84de8dbc58a112b07a873c9",
    "serviceType": "cloud.smarthq.service.toggle",
    "domainType": "cloud.smarthq.domain.power",
    "serviceDeviceType": "cloud.smarthq.device.refrigerator",
    "correlationId": "52b52c43-35dd-4d5a-8195-2d7dc316e080",
    "command": {
        "commandType": "cloud.smarthq.command.toggle.set",
        "on": true
    },
    "commandDateTime": "2020-10-26T12:55:37.003Z",
    "outcome": "cloud.smarthq.outcome.success",
    "outcomeDateTime": "2020-10-26T12:55:37.643Z"
}

Real-Time Device Updates¶

Overview¶

What is Pubsub?¶

WebSockets¶

Endpoint¶

Connecting¶

Ping & Pong¶

Limits¶

Next Steps¶

HTTPS / SNS Callbacks¶

Registering a Callback Endpoint¶

Configuring Event Messages¶

Event Delivery¶

Message Types¶

Event Configuration Messages¶

Event Messages¶