Due to the expansion of the range of devices that Shelly cloud will support in the future. This API will change all
deviceId: number type to
deviceId: string representation in the near future. All integrators must adapt to handle this change.
For easy transition, all packages in the Commands section will accept both type for a limited period of time.
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 firstname.lastname@example.org 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
Acquire integrator account
Request access token
Use the provided integrator
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>' \
Web Socket Connection
Open web sockets connection and authenticate with the 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 main that more than one open socket may be needed.
Server location will be provided on device registration with the
parameter. Integrator must keep at-least one open connections to a server, where
it has active users.