WebSocket Protocol

The WebSocket API provides real-time communication between the server and client SDKs during SOS events.

Connection

Patient and counselor SDKs connect with their JWT token as a query parameter:

wss://<domain>/ws?token=<jwt>

The server validates the JWT and associates the connection with the platform, session, and role (patient or counselor).

Message Flow

Counselor SDK              Counslr SOS              Patient SDK
     │                          │                        │
     │  POST /v1/platforms/     │                        │
     │  {platformId}/sessions/  │                        │
     │  {sessionId}/sos         │                        │
     │─────────────────────────►│                        │
     │                          │  location_request      │
     │                          │───────────────────────►│
     │                          │                        │
     │                          │  location_response     │
     │                          │◄───────────────────────│
     │                          │                        │
     │  psap_results            │                        │
     │◄─────────────────────────│                        │

Message Types

Server → Patient: location_request

Sent when a counselor triggers SOS. The Patient SDK responds automatically by submitting the patient’s current GPS coordinates.

{
  "type": "location_request",
  "sos_event_id": "sos-550e8400-e29b-41d4-a716-446655440000"
}

Patient → Server: location_response

Sent by the Patient SDK with the patient’s geolocation data. The accuracy field indicates the GPS precision in meters.

{
  "type": "location_response",
  "sos_event_id": "sos-550e8400-e29b-41d4-a716-446655440000",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "accuracy": 10.5
}

Server → Counselor: psap_results

Returned after the patient’s location is processed. Contains the nearest PSAP contacts with distances.

{
  "type": "psap_results",
  "sos_event_id": "sos-550e8400-e29b-41d4-a716-446655440000",
  "psaps": [
    {
      "name": "New York City 911",
      "phone": "2125551234",
      "distance_km": 1.2
    }
  ],
  "accuracy": 10.5
}

Error Handling

If the patient is unreachable when SOS is triggered:

  • The server cannot push a location_request
  • The SOS trigger response includes location_status: "unavailable" with a national 911 fallback contact
  • The counselor can still provide the fallback number to the patient through other means

Connection Lifecycle

  • Connect: SDK establishes WebSocket on initialization
  • Heartbeat: The SDK maintains the connection with periodic pings
  • Reconnect: SDKs automatically reconnect with exponential backoff if the connection drops
  • Disconnect: destroy() (Patient SDK) or disconnect() (Counselor SDK) closes the connection