Skip to main content

Notifications

Shelly components support two types of notifications through the methods NotifyStatus and NotifyEvent. The structure of the notification frames is described on the RPC Protocol page. More information about the notifications sent over each of the supported channels can found on this page.

Briefly:

  • notifications cannot be received over HTTP;
  • to start receiving notifications over websocket you have to send at least one request frame with a valid source (src);
  • to receive notifications over MQTT you have to subscribe to the topic shellydevicemodel-XXXXXXXXXXXX/events/rpc.

NotifyStatus#

This method notifies about change in the status of a component. It is defined by:

  • method: "NotifyStatus"
  • params:
    • ts: number, unix timestamp (in UTC)
    • COMPONENT: JSON object, with the same structure as the status object of the COMPONENT. Some or all unchanged attributes of the status object may not be visible. COMPONENT is substituted by the component type, (for example, cloud, wifi, mqtt). If more than one instance of this type of component are available, COMPONENT will be substituted by component_type:instance_id (e.g., switch:2, input:0)

Example 1:

Notify that a button has changed the output state of the switch with id=0.
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyStatus",
"params": {
"ts": 1631186545.04,
"switch:0": {
"id": 0,
"output": true,
"source": "button"
}
}
}

Example 2:

Notify that this device has lost connection to the cloud.
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyStatus",
"params": {
"ts": 1624348482.25,
"cloud": {
"connected": false
}
}
}

NotifyEvent#

This method notifies about an occurred event that is not necessarily reflected in the status of a component (e.g., pushed button, changed configuration, ...). It is defined by:

  • method: "NotifyEvent"
  • params:
    • ts: number, unix timestamp (in UTC)
    • events: array of JSON objects, containing all the events occurred. Each JSON object describes an event and contains different attributes according to the type of the event

The following attributes are common for every JSON object present in the events array:

  • component: string, denotes the type and instance id of the component from which the event originated, equal to either component_type:instance_id (e.g. switch:2) or component_type (e.g. sys, wifi)
  • id: number, the instance id of the component from which the event originated (if applicable)
  • event: string, name of the event (e.g. config_changed)
  • ts: number, unix timestamp (in UTC)

Example 1:

Notify that a button single push event has occurred.
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyEvent",
"params": {
"ts": 1631266595.44,
"events": [
{
"component": "input:0",
"id": 0,
"event": "single_push",
"ts": 1631266595.44
}
]
}
}

Common event notifications#

The following notifications are common for all functional and system components.

  • Configuration change

Example 1:

Notify that the configuration of input with id=0 has been changed.
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyEvent",
"params": {
"ts": 1631266460.71,
"events": [
{
"component": "input:0",
"id": 0,
"event": "config_changed",
"restart_required": false,
"ts": 1631266460.71
}
]
}
}