WebSocket Real-Time Streaming

Connect to the Haltless WebSocket for live sensor data, alerts, and machine status updates.

Connection

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

Authentication

After connecting, send your JWT access token as the first text message within the authentication timeout window. This keeps the token out of URL query strings and server logs.

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

ws.onopen = () => {
  // Send JWT as the first message
  ws.send(accessToken);
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Received:", data);
};

Close codes

Code	Meaning
4001	Invalid or expired token
4002	Authentication timeout (token not sent in time)
4003	Too many pending connections from this IP

Message types

Heartbeat

Sent by the server at regular intervals to keep the connection alive.

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

Sensor update

{
  "type": "sensor_update",
  "machine_id": "uuid",
  "metric_name": "temperature",
  "value": 73.2,
  "unit": "celsius",
  "timestamp": "2026-04-04T10:30:05Z"
}

Alert triggered

{
  "type": "alert",
  "alert_id": "uuid",
  "machine_id": "uuid",
  "severity": "critical",
  "message": "Temperature exceeded threshold",
  "metric_value": 87.3,
  "threshold_value": 85.0,
  "created_at": "2026-04-04T10:30:05Z"
}

Machine status change

{
  "type": "machine_status",
  "machine_id": "uuid",
  "old_status": "healthy",
  "new_status": "warning",
  "timestamp": "2026-04-04T10:30:05Z"
}

Connection limits

Limit	Value
Max pending (unauthenticated) connections per IP	Configurable
Auth timeout	Configurable
Heartbeat interval	Configurable

Best practices

1. Always handle reconnection , network issues will cause disconnects
2. Implement exponential backoff on reconnect attempts
3. Listen for heartbeats , if you miss several, proactively reconnect
4. Parse the type field first to determine how to handle each message
5. Refresh your JWT before it expires and reconnect with the new token

See the WebSocket Integration Guide for a complete implementation example.