WebSocket

Stream live sensor readings, alerts, and machine status changes over a single WebSocket connection. See the WebSocket Integration guide for a full client example.

Endpoint

wss://api.haltless.io/api/v1/ws/dashboard

Authentication

Connect first, then send your Bearer JWT access token as the first text message. Sending the token in the message body (rather than the URL) keeps it out of server logs and browser history. Send the token promptly after the socket opens; if it does not arrive in time, the connection is closed.

const ws = new WebSocket("wss://api.haltless.io/api/v1/ws/dashboard");

ws.onopen = () => {
  ws.send(accessToken); // first message must be your JWT
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "new_reading": /* … */ break;
    case "new_alert": /* … */ break;
    case "status_change": /* … */ break;
    case "heartbeat": /* keepalive */ break;
  }
};

Close codes

Code	Meaning
4001	Invalid or expired token, or the session was invalidated
4002	Authentication timed out (token not sent in time)
4008	Too many pending or open connections

Event types

Every message is JSON with a type field. Inspect type first, then read the fields for that event.

new_reading

A new sensor reading arrived.

{
  "type": "new_reading",
  "machine_id": "...",
  "metric_name": "temperature",
  "value": 73.2,
  "unit": "celsius",
  "timestamp": "2026-08-05T10:30:05Z"
}

new_alert

An alert was raised.

{
  "type": "new_alert",
  "alert_id": "...",
  "machine_id": "...",
  "severity": "critical",
  "message": "Temperature exceeded threshold"
}

status_change

A machine changed status.

{
  "type": "status_change",
  "machine_id": "...",
  "old_status": "healthy",
  "new_status": "warning"
}

heartbeat

Sent periodically by the server to keep the connection alive and confirm the session is still valid.

{
  "type": "heartbeat",
  "server_time": "2026-08-05T10:30:00Z"
}

Best practices

1. Reconnect with exponential backoff on disconnect.
2. Watch for heartbeats; if several are missed, reconnect.
3. Refresh your JWT before it expires and reconnect with the new token.
4. Branch on the type field before reading event-specific fields.