Skip to main content

​
Overview

This guide walks you through setting up the Suki Headless Web SDK in your React application, from installation to creating your first ambient recording session.

​
Prerequisites

For the rest of this documentation, we assume the following setup is complete:
  • You have received your partnerId from Suki.
  • Your host URLs are on the Suki allowlist.
  • Your partner configuration in the Suki Platform points to your correct JWKS endpoint.
  • Your JWT token contains the key that you specified as your User identifier field.
Refer to the Prerequisites guide for more information.

​
Install The Package

To begin, install the Suki Headless Web SDK package in your React project: 
pnpm add @suki-sdk/platform-react
For detailed setup instructions, refer to the Installation guide.

​
Authenticate Users

The first step is to authenticate users using the useAuth hook. This hook manages user identity and provides access tokens needed for all SDK operations.
React
import { useAuth } from '@suki-sdk/platform-react';

function App() {
  const {
    isLoggedIn,
    isPending,
    error,
    login
  } = useAuth({
    partnerId: 'your-partner-id', // Required: Replace with your actual partner ID
    partnerToken: 'your-partner-token', // Required: Replace with your actual partner token
    autoRegister: true, // Optional: Automatically register users if they don't exist
    loginOnMount: true, // Optional: Sign in automatically when component mounts
    providerName: 'Dr. John Doe', // Required for auto-registration
    providerOrgId: 'org-123', // Required for auto-registration
    providerSpecialty: 'Cardiology' // Required for auto-registration
  });

  if (isPending) {
    return <div>Signing in...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  if (!isLoggedIn) {
    return <button onClick={login}>Sign In</button>;
  }

  return <div>Ready to use Suki Headless Web SDK</div>;
}
If you set autoRegister: true, you must provide providerName, providerOrgId, and providerSpecialty. If you prefer manual registration, set autoRegister: false and use the registerUser method. See the Authentication Hook guide for more details.

​
Create Ambient Session

Once authenticated, create an ambient session using the useAmbient hook. This creates a session container that you’ll use for recording.
React
import { useEffect } from 'react';
import { useAmbient } from '@suki-sdk/platform-react';

function SessionCreator({ onSessionReady }) {
  const {
    ambientSessionId,
    session: { create, isPending, isSuccess, error }
  } = useAmbient();

  // Create session when component mounts
  useEffect(() => {
    create();
  }, [create]);

  // Pass session ID to parent when ready
  useEffect(() => {
    if (isSuccess && ambientSessionId) {
      onSessionReady(ambientSessionId);
    }
  }, [isSuccess, ambientSessionId, onSessionReady]);

  if (isPending) {
    return <div>Creating session...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return null;
}
You must wait for isSuccess to be true before attempting to use the ambientSessionId. Passing an undefined ID to the recording hooks will cause errors.

​
Manage Recording

Use the useAmbientSession hook to control recording. This hook provides methods to start, pause, resume, and submit recordings, along with session status.
React
import { useAmbientSession } from '@suki-sdk/platform-react';

function Recorder({ sessionId }) {
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType, // New in v0.2.2
    setSessionContext
  } = useAmbientSession({
    ambientSessionId: sessionId,
    onAudioChunkAvailable: (chunk) => {
      // Optional: Use audio chunks for visualization
      console.log('Audio chunk received:', chunk);
    }
  });

  // Set session context after starting
  const handleStart = async () => {
    await start();
    // Provide context to improve note generation
    await setSessionContext({
      patient: {
        dob: '1980-01-15',
        sex: 'M'
      },
      provider: {
        specialty: 'Cardiology',
        role: 'Attending Physician'
      },
      visit: {
        visit_type: 'Follow-up',
        encounter_type: 'Office Visit',
        reason_for_visit: 'Chest pain evaluation',
        chief_complaint: 'Chest pain'
      }
    });
  };

  return (
    <div>
      <h3>Status: {sessionStatus}</h3>
      {sessionType === 'offline' && ( // added in v0.2.2
        <p>Session will sync when online</p>
      )}
      
      {sessionStatus === 'created' && (
        <button onClick={handleStart}>Start Recording</button>
      )}
      
      {sessionStatus === 'recording' && (
        <>
          <button onClick={pause}>Pause</button>
          <button onClick={submit}>Finish & Submit</button>
        </>
      )}
      
      {sessionStatus === 'paused' && (
        <>
          <button onClick={resume}>Resume</button>
          <button onClick={submit}>Finish & Submit</button>
        </>
      )}
    </div>
  );
}
Always use setSessionContext to provide relevant patient or encounter details. This context acts as a hint for the AI, resulting in significantly higher quality clinical notes.

​
Complete Example

Here’s a complete example that brings everything together:
React
import { useState, useEffect } from 'react';
import { useAuth, useAmbient, useAmbientSession } from '@suki-sdk/platform-react';

function SukiRecorder() {
  const [sessionId, setSessionId] = useState(null);

  // Step 1: Authenticate
  const { isLoggedIn, isPending: authPending } = useAuth({
    partnerId: 'your-partner-id', // Required, replace with your actual partner ID
    partnerToken: 'your-partner-token', // Required, replace with your actual partner token
    autoRegister: true, // Optional, set to true to automatically register the user if they don't exist
    loginOnMount: true, // Optional, set to true to sign in automatically when the component mounts
    providerName: 'Dr. John Doe', // Required for auto-registration
    providerOrgId: 'org-123', // Required for auto-registration
    providerSpecialty: 'Cardiology' // Required for auto-registration
  });

  // Step 2: Create session
  const {
    ambientSessionId,
    session: { create, isSuccess: sessionCreated }
  } = useAmbient();

  useEffect(() => {
    if (isLoggedIn && !sessionCreated) {
      create();
    }
  }, [isLoggedIn, sessionCreated, create]);

  useEffect(() => {
    if (ambientSessionId) {
      setSessionId(ambientSessionId);
    }
  }, [ambientSessionId]);

  // Step 3: Manage recording
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType, // New in v0.2.2
  } = useAmbientSession({
    ambientSessionId: sessionId
  });

  if (authPending) {
    return <div>Authenticating...</div>;
  }

  if (!isLoggedIn) {
    return <div>Please sign in</div>;
  }

  if (!sessionId) {
    return <div>Creating session...</div>;
  }

  return (
    <div>
      <h2>Recording Status: {sessionStatus}</h2>
      {sessionType === 'offline' && ( // added in v0.2.2
        <p>Session will sync when online</p>
      )}
      
      {sessionStatus === 'created' && (
        <button onClick={start}>Start Recording</button>
      )}
      
      {sessionStatus === 'recording' && (
        <>
          <button onClick={pause}>Pause</button>
          <button onClick={submit}>Submit</button>
        </>
      )}
      
      {sessionStatus === 'paused' && (
        <>
          <button onClick={resume}>Resume</button>
          <button onClick={submit}>Submit</button>
        </>
      )}
    </div>
  );
}

​
Next Steps

Refer to the following guides to learn more: