Headless Web SDK Quickstart

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. What you will do

Install @suki-sdk/platform-react in your React project.
Wrap your app with PlatformClient and PlatformClientProvider at the root so all SDK hooks share one client.
Authenticate with useAuth inside that tree so users are signed in and tokens are available.
Create an ambient session with useAmbient, then control recording with useAmbientSession (start, pause, resume, submit, and optional context).
Wire up a minimal end-to-end flow using the complete example as a reference.

Using an AI coding tool?Copy the following prompt to add the Suki developer documentation as a skill and MCP server to your tool for better AI-assisted coding during the integration process. For all AI options (contextual menu, llms.txt, and skill.md), refer to AI-optimized documentation.

Install the Suki developer docs as a skill to get context on Suki's developer tools, APIs, and SDKs. Add the MCP server for documentation search.

Open in Cursor

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

npm install @suki-sdk/platform-react

yarn add @suki-sdk/platform-react

For detailed setup instructions, refer to the Installation guide.

Required configuration

Create a single PlatformClient instance and wrap your entire application with PlatformClientProvider. Hooks such as useAuth, useAmbient, and useAmbientSession must run under this provider.

React

import { PlatformClient, PlatformClientProvider } from '@suki-sdk/platform-react';

const client = new PlatformClient({
  env: "staging",
  enableDebug: true,
  logLevel: "error"
});

function App() {
  return (
    <PlatformClientProvider>
      <YourApp />
    </PlatformClientProvider>
  );
}

Authenticate with useAuth

After the provider wraps your app, use useAuth in a child component (for example YourApp). This hook manages user identity and provides access tokens needed for all SDK operations.

React

import { useAuth } from '@suki-sdk/platform-react';

function YourApp() {
  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 {
  PlatformClient,
  PlatformClientProvider,
  useAuth,
  useAmbient,
  useAmbientSession
} from '@suki-sdk/platform-react';

const client = new PlatformClient({
  env: 'staging',
  enableDebug: true,
  logLevel: 'error'
});

function App() {
  return (
    <PlatformClientProvider>
      <SukiRecorder />
    </PlatformClientProvider>
  );
}

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

  // Step 1: Authenticate (under PlatformClientProvider)
  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: 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
  });

  // 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: Platform client and provider - Understand how to use PlatformClient and PlatformClientProvider Authentication hook - Learn more about authentication options and token management Create ambient session - Understand session creation in detail Manage ambient session - Explore all recording controls and session context Error handling - Learn how to handle errors gracefully Offline mode - Understand how the SDK handles network interruptions

​Prerequisites

​Install the package

​Required configuration

​Authenticate with useAuth

​Create ambient session

​Manage recording

​Complete example

​Next steps

Prerequisites

Install the package

Required configuration

Authenticate with useAuth

Create ambient session

Manage recording

Complete example

Next steps