Skip to main content

Communication

Established WS connection - basic package types & structure.

Address​

Open web sockets connection and authenticate with the JWT to address

wss://<HOST>:6113/shelly/wss/hk_sock?t=<JWT>

The integrator learns the hosts it need to connect via User consent/Permissions Grant process from the host parameter provided to Integrator callback url.

The <JWT> token is obtained as explained at Getting Started

Events​

Events that Shelly cloud sends.

Shelly:StatusOnChange​

Device state change.

{
    event: "Shelly:StatusOnChange", // EVENT_NAME
    deviceId: string,               // DEVICE_ID
    status: object                  // DEVICE_SPECIFIC_STATUS_STRUCTURE
}

Shelly:Settings​

Device settings change. Sent when a setting is changed in the device.

{
    event: "Shelly:Settings", // EVENT_NAME
    deviceId: string,         // DEVICE_ID
    settings: object          // DEVICE_SPECIFIC_SETTINGS_STRUCTURE
}

Shelly:Online​

Sent when device changes online state.

{
    event: "Shelly:Online", // EVENT_NAME
    deviceId: string,       // DEVICE_ID
    online: number          // DEVICE_ONLINE_STATUS - 1 for online, 0 for offline
}

Commands​

Request for Relay & Light​

Request
{
    event: "Shelly:CommandRequest", // EVENT_NAME
    trid: number                    // TRANSACTION_ID
    deviceId: string,               // DEVICE_ID
    data: {
        cmd: string,                // COMMAND_NAME "relay" | "light"
        params: {
            id: number,             // DEVICE_CHANNEL
            turn: string            // COMMAND_ACTION "on" | "off" | "toggle"
        }
    }
}

Request for Roller​

Request
{
    event: "Shelly:CommandRequest", // EVENT_NAME
    trid: number                    // TRANSACTION_ID
    deviceId: string,               // DEVICE_ID
    data: {
        cmd: string,                // COMMAND_NAME "roller"
        params: {
            id: number,             // DEVICE_CHANNEL
            go: string              // COMMAND_ACTION "stop" | "open" | "close"
        }
    }
}

Request for Roller to Position​

This command only works if device is calibrated.

Request
{
    event: "Shelly:CommandRequest", // EVENT_NAME
    trid: number                    // TRANSACTION_ID
    deviceId: string,               // DEVICE_ID
    data: {
        cmd: string,                // COMMAND_NAME "roller_to_pos"
        params: {
            id: number,             // DEVICE_CHANNEL
            pos: number             // POSITION_IN_PERCENT
            rel: number,            // RELATIVE_POSITION_IN_PERCENT
            slat_pos:number,        // SLAT_POSITION
            slat_rel:number         // RELATIVE_SLAT_POSITION
        }
    }
}
  • id identifies the roller/cover channel to change, starts from 0. It must be present even for single channel devices.
  • pos is the position expressed in percent in range 0 to 100.
  • rel is relative move in %, allowed range [-100..100]. pos and rel can't be provided simultaneously.
  • slat_pos same as pos but for slats position (if supported by the device).
  • slat_rel same as rel but for slats position (if supported by the device) slat_pos and slat_rel can't be provided simultaneously.

Check the device documentation for more information.

Command Response​

Response
{
    event: "Shelly:CommandResponse", // EVENT_NAME
    trid: number,                    // TRANSACTION_ID
    deviceId: string,                // DEVICE_ID
    user: number,                    // USER_ID device owner
    data: {
        isok: boolean;               // SUCCESS_FLAG
        res?: string;                // MESSAGE optional
    }
}

Actions​

Result constants - data.result

  • OK - All is good.
  • UNAUTHORIZED - Device access in not authorized.
  • WRONG_API_PARAMETERS - Malformed request.
  • WRONG_HOST - Request was made on a wrong host.

Error response WRONG_HOST has an extra parameter host, indicating the actual location of the device. This does not guarantee that the device is currently online there.

Response
{
    event: "Integrator:ActionResponse", // event name
    trid: number,                       // transaction id
    user: string,                       // integrator tag
    data: {
        result: "WRONG_HOST",
        deviceId: string,
        host: string
    }
}

Device Verify​

Verify that the device has a valid integration.

Request
{
    event: "Integrator:ActionRequest", // event name
    trid: number,                      // transaction id
    data: {
        action: "DeviceVerify",        // action "DeviceVerify"
        deviceId: string,              // device id,
    }
}
Response
{
    event: "Integrator:ActionResponse", // event name
    trid: number,                       // transaction id
    user: string,                       // integrator tag
    data: {
        result: string,                 // result constant
        deviceId?: string,              // optional (if provided in request)
        deviceType?: string,            // optional (if result is "OK" and device is online)
        deviceCode?: string,            // optional (if result is "OK" and device is online)
        deviceStatus?: {},              // optional (if result is "OK" and device is online)
        accessGroups?: string           // optional (if result is "OK")
    }
}

Keys deviceType, deviceCode and deviceStatus are only available if the device in online in the cloud!

accessGroups

Access given to the integrator for the specific device by the user. Consists of a HEX string value, represented by a single byte, giving us 8 possible groups for access represented by each bit of the byte. Currently there is only one - control that is indicated by the first bit turned ON.

So an accessGroups of 00 means only state changes are sent and no control is present, we refer to this as read-only. Then accessGroups of 01 means group "control" is also activated..

  • 00 (hex) -> 0 0 0 0 0 0 0 0 (binary) read-only
  • 01 (hex) -> 0 0 0 0 0 0 0 1 (binary) active control-group

Device Get Settings​

Retrieve device settings, only if the device in online in the cloud.

Request
{
    event: "Integrator:ActionRequest", // event name
    trid: number,                      // transaction id
    data: {
        action: "DeviceGetSettings",   // action "DeviceVerify"
        deviceId: string,              // device id,
    }
}
Response
{
    event: "Integrator:ActionResponse", // event name
    trid: number,                       // transaction id
    user: string,                       // integrator tag
    data: {
        result: string,                 // result constant
        deviceId?: string,              // optional (if provided in request)
        deviceType?: string,            // optional (if device is online)
        deviceCode?: string,            // optional (if device is online)
        deviceSettings?: {},            // optional (if device is online)
    }
}