Heartbeat and Reconnection

This page describes the application-layer heartbeat mechanism and the reconnection strategy so that clients can recover correctly after connection loss.

Application-Layer Heartbeat

Clients may periodically send session.ping to confirm that the connection and session are still usable.

Request:

{
  "type": "request",
  "requestId": "req_ping_001",
  "topic": "session.ping",
  "data": {}
}

Reply:

{
  "type": "reply",
  "requestId": "req_ping_001",
  "topic": "session.ping",
  "success": true,
  "data": {}
}

Heartbeat Frequency

Clients should send session.ping every 30 seconds.

If heartbeats are too frequent, the service may return session.error:

{
  "type": "event",
  "topic": "session.error",
  "data": {
    "code": "RATE_LIMITED",
    "message": "Rate limit was exceeded."
  }
}

Heartbeat Timeout

The connection may be closed if the client sends no valid messages for a long period.

The client should establish a new connection after the old one closes.

Reconnection Rules

• The client may reconnect after an abnormal connection close
• Confirm that the access token is still valid before reconnecting
• If the token has expired, obtain a new access token before reconnecting
• Use exponential backoff with jitter when reconnecting
• Do not retry reconnections in a tight loop

State Recovery

WebSocket does not guarantee replay of events that were missed while the client was disconnected.

After reconnecting, the client should refresh the current state as needed:

• Call Get Device
• Call Get Command Result
• If WebSocket status queries are already in use, send device.status.get