Getting Started

This guide walks through integrating Counslr SOS into a telehealth platform.

Prerequisites

  • A registered platform with API credentials (contact Counslr for onboarding)
  • A server-side application capable of storing secret API keys
  • A browser-based telehealth UI where SDKs can be embedded

Integration Overview

Platform Backend             Counslr SOS API     Browser (Patient + Counselor)
     │                              │                          │
     │ 1. POST /v1/platforms/       │                          │
     │    {platformId}/sessions     │                          │
     │   (X-API-Key: sk_live_*)     │                          │
     │─────────────────────────────▶│                          │
     │◀─────────────────────────────│                          │
     │   session_id, tokens         │                          │
     │                              │                          │
     │ 2. Pass tokens to SDKs ────────────────────────────────▶│
     │                              │  3. SDKs connect WS      │
     │                              │◀─────────────────────────│
     │                              │                          │
     │                              │  4. Counselor triggers   │
     │                              │     SOS via SDK          │
     │                              │◀─────────────────────────│
     │                              │                          │
     │                              │  5. Patient auto-submits │
     │                              │     location via SDK     │
     │                              │◀─────────────────────────│
     │                              │                          │
     │                              │  6. PSAP results via WS  │
     │                              │─────────────────────────▶│

Step 1: Create a Session

From your backend server, start a session using your secret API key:

curl -X POST https://api.counslr-sos.example.com/v1/platforms/{your-platform-id}/sessions \
  -H "X-API-Key: sk_live_a1b2c3d4_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "meeting_id": "room-123",
    "counselor_id": "counselor-456",
    "patient_id": "patient-789",
    "expires_in_minutes": 60
  }'

The response includes JWTs for both the patient and counselor SDKs:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "active",
  "patient_token": "<jwt>",
  "counselor_token": "<jwt>",
  "expires_at": "2026-02-12T15:00:00Z"
}

Step 2: Initialize the SDKs

Pass the JWT tokens to the browser-side SDKs. See SDK Integration for detailed setup instructions.

Patient browser:

import { CounslrPatientSDK } from '@counslr/patient-web-sdk';

const patientSDK = new CounslrPatientSDK({
  token: patientToken,
  apiBaseUrl: 'https://api.counslr-sos.example.com',
  wsUrl: 'wss://ws.counslr-sos.example.com',
});
patientSDK.init();

Counselor browser:

import { CounslrCounselorSDK } from '@counslr/counselor-sdk';

const counselorSDK = new CounslrCounselorSDK({
  sessionToken: counselorToken,
  wsUrl: 'wss://ws.counslr-sos.example.com',
  onPSAPResults: (results) => {
    console.log('Nearest PSAPs:', results.psaps);
  },
});
counselorSDK.connect();

Step 3: Trigger SOS

When a counselor triggers an SOS, the system automatically:

  1. Transitions the session to sos state
  2. Sends a location_request to the patient via WebSocket
  3. The Patient SDK auto-submits the patient’s GPS coordinates
  4. Performs a geospatial PSAP lookup
  5. Returns nearest PSAP contacts to both SDKs
await counselorSDK.trigger({ sessionId: session.session_id });

Step 4: End the Session

From your backend server:

curl -X POST https://api.counslr-sos.example.com/v1/platforms/{your-platform-id}/sessions/550e8400-e29b-41d4-a716-446655440000/end \
  -H "X-API-Key: sk_live_a1b2c3d4_your_secret_key"

Next Steps