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 integrator. 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

Iteractions Diagram​

sequenceDiagram box rgb(250, 250, 250) Integrator participant Frontend participant Backend end box rgb(250, 250, 250) Shelly Cloud participant Device Permissions Grant participant OAuth Token Exchange participant Device Data Streams end Frontend->>+Device Permissions Grant: Send tag and callback url Note right of Device Permissions Grant: User login, selects devices to allow to Integrator Device Permissions Grant->>-Backend: User selected device ids and shelly servers that devices belong to Backend->>+OAuth Token Exchange: Request access token with tag and token OAuth Token Exchange->>-Backend: Grant Acces token Backend->>+Device Data Streams: Connect with access token to device proper device server Device Data Streams->>Backend: Send device statuses from all users that have enabled Integrator service for their devices Backend->>Device Data Streams: Send command Device Data Streams->>-Backend: Receive command response

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.

Device Permission Grant​

The Users grant Integrator the right to monitor their devices on

https://my.shelly.cloud/integrator.html?itg=<TAG>&cb=<URL>

The integrator should have the <URL> provided with cb arg always accessible so the Integrator backend can learn about new devices that need to be monitored and new shelly cloud server that need to be connected. See User consent/Permissions Grant

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, one to each server, where Integrator have customers on. We only allow one active connection per server.

Proper server name for WSS connection will be provided on device permission grant with the host parameter. Integrator must keep at-least one open connections to a server, where it has active users.

N.B. This API delivers data to single location in Integrator infrastructure. If the Integrator need to use this information in multiple servers/datacenters, it's up to the Integrator to distribute the data inside it's infrastructure