Skip to main content

Real-Time (WebSockets)

Authentication​

To authenticate with the real-time service, you need to get a temporary authentication ticket.

caution

This ticket is unique to the current (JWT) user token and will be valid for 1 minute.

Getting a WebSocket ticket​

You can get a ticket by making a GET request to /ws/ticket. You'll then get a response like below, where the key ticket holds the WebSocket ticket.

{
  "ticket": "eyJhbGci..."
}

Using the ticket to establish a connection with the real-time service​

To establish a real-time connection, open a WebSocket connection to wss://ws.experimental.cloudgarden.nl?token=TICKET and replace TICKET with your ticket.

Subscribing to a topic​

info

Dynamic topic parts are surrounded by {{ and }}. A dynamic part is expressed as: ENTITY.ENTITY_PROPERTY_NAME.

You can subscribe to a data topic by sending a JSON subscription package like this (you can find a list of all topics here):

{
  "type": "subscribe",
  "data":{
    "topics":["sensors/{{SENSOR.deviceId}}/measurements"]
    }
}
tip

Instead of replacing a dynamic part with the actual identifier, you can also use the MQTT like + wildcard to resolve all entity ids of a user.

caution

If you want to subscribe to tenant data, you need to prepend the topic with tenants/TENANT.id/. For example, if you want to subscribe to the measurement topic of a tenant sensor, you'd use: tenants/TENANT.id/sensors/+/measurements.

Unsubscribing from a topic​

To unsubscribe from a topic, you only have to change the type value from subscribe to unsubscribe.

{
  "type": "unsubscribe",
  "data":{
    "topics":["sensors/{{SENSOR.deviceId}}/measurements"]
    }
}