Skip to main content

Getting Started

Introduction​

We have developed connectivity Cloud-to-Cloud API for integration, control and telemetry collection from our devices. This documentation is intended for third party integrators, that would like to monitor and control Shelly devices that are connected to our cloud systems. It allows centralized streaming of status data from many shelly accounts to a single point for data ingest. Basic control over the devices is also possible. An integrator account holding integrator's communications endpoints must be created. For creation of the integrator's account and for obtaining a license you should contact us at support@shelly.cloud or fill this form Licenses for personal use are not provided. Device owners willing to use integrator's services have to log into their Shelly Cloud account and give consent for sharing a set of their devices with any intergrator. They can also revoke that consent later.

If your use case is more shelly account centric consider using Real Time Events API where similar functionality is offered but authentication is OAuth based via the Shelly account owner's credentials

If you want to be independent from the Shelly Cloud and you use Gen 2 devices, we advise you to check - Shelly Fleet Management

Expected architecture on the integrator side​

Shelly CloudRealtime Event Handling Service1 WebSocketper Shelly serverDATABASEApplicationbackendUser ConsentAdd/Remove device for tracking ControlControlStatusStatisticsAPP UserAuthenticationShelly UserConsent

Acquire integrator account​

Contact us at support@allterco.com or fill this form. What you'll receive is tag & token unique identifiers.

Request access token​

Use the provided integrator tag and token to acquire JWT (Access Token valid 24h) used for issuing WSS connection. Valid JWT is required when issuing a new connection. The connection can persist indefinitely.

curl -X POST 'https://api.shelly.cloud/integrator/get_access_token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'itg=<INTEGRATOR_TAG>' \
    --data-urlencode 'token=<INTEGRATOR_TOKEN>'

{
    isok: true,
    data: "<JWT>"
}

Web Socket Connection​

Open web sockets connection and authenticate with the JWT.

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

There are multiple Shelly cloud servers, each user and his/hers devices always connect to the same server. The WSS connection to a Shelly server will receive the data for all devices with enabled integration connected to that server. Keep in mind that more than one open socket may be needed, if you have customers on different Shelly servers. We only allow one active connection per server.

Server location will be provided on device registration with the host parameter. Integrator must keep at-least one open connections to a server, where it has active users.

sequenceDiagram Integrator Cloud->>Shelly support: Contact support for license Shelly support->>Integrator Cloud: Provide tag and token Integrator Cloud->>Shelly Cloud: Request short lived (24h) JWT Shelly Cloud->>Integrator Cloud: JWT loop Secure WebSocket, provide acquired JWT Integrator Cloud->>Shelly Cloud: control Shelly Cloud->>Integrator Cloud: notifications end Integrator Cloud->>Shelly Cloud: Device registration, deregistration