Heartbeats and Reconnection

WebSocket is a long-lived connection, but network devices, proxies, and service maintenance can interrupt it. Clients must implement heartbeats, disconnect detection, and reconnection.

Heartbeats

Use both:

1. WebSocket protocol Ping/Pong to detect network connectivity.
2. session.ping to confirm application-level message handling.

session.ping reply:

{
  "type": "reply",
  "requestId": "req_ping_001",
  "code": "SUCCESS",
  "message": "OK.",
  "data": {}
}

Follow Rate Limits and Retries for heartbeat frequency. Do not use device-state queries as heartbeats.

Reconnection Flow

1. Detect a closed connection or heartbeat timeout.
2. Apply exponential backoff with jitter.
3. Use a valid access token to create a new WebSocket ticket.
4. Establish a new connection.
5. Send one device.state.get for each business-critical device.
6. Resume event processing.

Each ticket is single-use and cannot be reused for reconnection.

Event Continuity

WebSocket does not replay events missed while disconnected. Applications should:

• Persist important events promptly.
• Use stateUpdatedAt to prevent older state from replacing newer state.
• Query critical devices after reconnecting instead of refreshing every device in the account.