WebSocket API
Connect to real-time device updates. Requires authentication via API key.
Connection
wss://api.example.com/realtime?api_key=your-api-key
X-API-Key header if your WebSocket client supports custom headers.
Connection Response
On successful connection:
{
"type": "connected",
"connectionId": "conn-1702812600000-1"
}
Unauthorized connections receive 401 Unauthorized and are closed immediately.
Client Messages
Subscribe to Devices
Subscribe to receive updates for specific devices.
{
"type": "subscribe",
"hardwareIds": ["ABC123", "DEF456"]
}
{
"type": "subscribed",
"hardwareIds": ["ABC123", "DEF456"]
}
Unsubscribe from Devices
Stop receiving updates for specific devices.
{
"type": "unsubscribe",
"hardwareIds": ["ABC123"]
}
{
"type": "unsubscribed",
"hardwareIds": ["ABC123"]
}
Send Command
Send a command to a device via WebSocket.
{
"type": "command",
"hardwareId": "ABC123",
"command": "lock",
"params": {}
}
{
"type": "command_sent",
"commandId": "x1y2z3w4",
"hardwareId": "ABC123",
"command": "lock",
"status": "pending"
}
Server Messages
Device Data Update
Sent when a subscribed device reports telemetry.
{
"type": "device_data",
"hardwareId": "ABC123",
"deviceId": "a1b2c3d4",
"payload": {
"lat": 37.7749,
"long": -122.4194,
"speed": 15.5,
"battery_voltage": 12.4,
"lock_status": 0
},
"timestamp": "2025-12-17T10:30:00.000Z",
"updated_at": "2025-12-17T10:30:00.000Z",
"last_responded_at": "2025-12-17T10:30:00.000Z"
}
- updated_at: Last time the device document was written (any update).
- last_responded_at (optional): Last time we received device-originated data (telemetry/status with payload). Omitted when never set. Use this in the UI for “last responded”; it is not updated by LWT or online-status-only.
Device Status Update
Sent when a device goes online or offline.
{
"type": "device_status",
"hardwareId": "ABC123",
"deviceId": "a1b2c3d4",
"payload": {
"is_online": false
},
"timestamp": "2025-12-17T10:30:00.000Z",
"updated_at": "2025-12-17T10:30:00.000Z",
"last_responded_at": "2025-12-17T10:30:00.000Z"
}
Error Message
Sent when an error occurs.
{
"type": "error",
"message": "hardwareIds must be an array"
}
JavaScript Example
const ws = new WebSocket("wss://api.example.com/realtime?api_key=your-api-key");
ws.onopen = () => {
console.log("Connected");
// Subscribe to devices
ws.send(
JSON.stringify({
type: "subscribe",
hardwareIds: ["ABC123", "DEF456"],
}),
);
};
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "connected":
console.log("Connection ID:", msg.connectionId);
break;
case "subscribed":
console.log("Subscribed to:", msg.hardwareIds);
break;
case "device_data":
console.log(`Device ${msg.hardwareId}:`, msg.payload);
break;
case "device_status":
console.log(`Device ${msg.hardwareId} online:`, msg.payload.is_online);
break;
case "error":
console.error("Error:", msg.message);
break;
}
};
ws.onerror = (error) => {
console.error("WebSocket error:", error);
};
ws.onclose = () => {
console.log("Disconnected");
};
// Send a command
const sendCommand = (hardwareId, command) => {
ws.send(
JSON.stringify({
type: "command",
hardwareId,
command,
params: {},
}),
);
};
// Example: lock device
sendCommand("ABC123", "lock");
Message Types Summary
Client → Server
| Type | Description |
|---|
subscribe | Subscribe to device updates |
unsubscribe | Unsubscribe from device updates |
command | Send command to device |
Server → Client
| Type | Description |
|---|
connected | Connection established |
subscribed | Subscription confirmed |
unsubscribed | Unsubscription confirmed |
device_data | Device telemetry update |
device_status | Device online/offline status |
command_sent | Command queued |
error | Error occurred |