Skip to main content

Getting Started

caution

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.

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@allterco.com 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 main that more than one open socket may be needed.

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.