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 <shelly-id_>/events/rpc.

NotifyStatus

This method notifies about change in the status of a component, and carries information about the changes which occurred. It is defined by:

• method: "NotifyStatus"
• params:

Property	Type	Description
ts	number	Unix timestamp (in UTC)
component	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 must be 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:id (e.g., switch:2, input:0)

The intended use of these notifications is to overlay the changes from NotifyStatus over a known status. This should yield identical results to what would be returned by a fresh GetStatus call.

Certain status keys will only exist in certain situations. When such keys disappear from the status payload, the NotifyStatus payload which notifies about the change will include the key with a null value.

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
      }
   }
}

Example 3:

Notify that config for this device has changed.

{
   "src": "shellyplus1-a8032abe54dc",
   "dst": "user_1",
   "method": "NotifyStatus",
   "params": {
      "ts": 1655369046.4,
      "sys": {
         "cfg_rev": 19
      }
   }
}

NotifyFullStatus

Since version 0.11.0

This method has the same semantics as NotifyStatus, but the payload contains the full status of all components.

• method: "NotifyFullStatus"
• params:
  • ts: number, unix timestamp (in UTC)
  • <component>: JSON object, with the same structure as the status object of the component.

Example 1:

{
   "src": "shellyplusht-f008d1d8b8b8",
   "dst": "user_1",
   "method": "NotifyFullStatus",
   "params": {
      "ts": 1631186545.04,
      "ble": {},
      "cloud": {
         "connected": false
      },
      "mqtt": {
         "connected": false
      },
      "sys": {
         "mac": "F008D1E62338",
         "restart_required": false,
         "time": null,
         "unixtime": null,
         "uptime": 41,
         "ram_size": 254948,
         "ram_free": 146620,
         "fs_size": 458752,
         "fs_free": 229376,
         "cfg_rev": 0,
         "available_updates": {}
      },
      "wifi": {
         "sta_ip": null,
         "status": "disconnected",
         "ssid": null,
         "rssi": 0
      },
      "temperature:0": {
         "id": 0,
         "tC": 20.0,
         "tF": 68.0
      },
      "humidity:0": {
         "id": 0,
         "rh": 50.0
      },
      "devicepower:0": {
         "id": 0,
         "battery": {
            "V": 4.59,
            "percent": 11
         },
         "external": {
            "present": false
         }
      },
      "ht_ui": {}
   }
}

The notification is emitted:

• over outbound websocket RPC channel for all devices
• over outbound websocket, MQTT and outbound UDP channels on battery-operated (sleeping) devices.

NotifyEvent

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

• method: "NotifyEvent"

• params:

  Property	Type	Description
  ts	number	Unix timestamp (in UTC)
  events	array of 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:

Property	Type	Description
ts	number	Unix timestamp (in UTC)
component	string	Component key (component_type[:id], e.g. switch:0; wifi)
id	number	Component id
event	string	Event name

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
         }
      ]
   }
}

Example 2:

Notify that a sys button push event has occurred.

{
   "src": "shellypro1pm-f008d3256874",
   "dst": "user_1",
   "method": "NotifyEvent",
   "params": {
      "ts": 1713361785.51,
      "events": [
         {
            "component": "sys",
            "event": "sys_btn_push",
            "ts": 1713361785.51
         }
      ]
   }
}

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,
            "cfg_rev": 18
         }
      ]
   }
}