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​

Command Request - 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"
        }
    }
}

Command Request - 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"
        }
    }
}

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

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​

Device Verify. Verify that the device has a valid integration.

Request
{
    event: "Integrator:ActionRequest", // EVENT_NAME
    trid: number,                      // TRANSACTION_ID,
    data: {
        action: "DeviceVerify",        // ACTION_NAME "DeviceVerify"
        deviceId: string,              // DEVICE_ID,
    }
}
Response
{
    event: "Integrator:ActionResponse", // EVENT_NAME
    trid: number,                       // TRANSACTION_ID,
    user: string,                       // INTEGRATOR_TAG
    data: {
        result: string,                 // STATUS "OK" | "UNAUTHORIZED" | "WRONG_API_PARAMETERS"
        deviceId?: string,              // DEVICE_ID     optional (if provided in request)
        deviceType?: string,            // DEVICE_TYPE   optional (if device is online)
        deviceCode?: string,            // DEVICE_CODE   optional (if device is online)
        deviceStatus?: {},              // DEVICE_STATUS optional (if device is online)
        accessGroups?: string           // ACCESS_GROUP  optional (only on STATUS "OK", HEX string)
    }
}

Value of result attribute means:

  • OK - This deviceId has integration enabled.
  • UNAUTHORIZED - This device in not authorized.
  • WRONG_API_PARAMETERS - Malformed request.

Key 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