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 prompt below to point your agent at the Ambient skill and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the Ambient skill and connect the documentation MCP.

Open in Cursor

Prerequisites

For the rest of this documentation, we assume the following setup is complete:

You run a React 18+ app with a standard bundler (Vite, Webpack, or Next.js).
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.
You can request microphone access over HTTPS in production (and set iframe allow attributes if your app is embedded).

Refer to the Prerequisites guide for the full checklist.

Create your first Headless Web SDK Ambient session

Install the Package

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.

Configure the Platform Client

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 client={client}>
      <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: 'FAMILY_MEDICINE' // 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 an 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({ encounterId: 'your-encounter-id' });
  }, [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 { useState } from '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);
    }
  });

  // sessionStatus is only "created" | "submitted" | "completed" | "cancelled".
  // Track recording vs paused locally.
  const [phase, setPhase] = useState('idle'); // 'idle' | 'recording' | 'paused'

  const handleStart = async () => {
    await start();
    setPhase('recording');
    await setSessionContext({
      patient: {
        dob: '1980-01-15',
        sex: 'M'
      },
      provider: {
        specialty: 'FAMILY_MEDICINE',
        role: 'Attending Physician'
      },
      visit: {
        visit_type: 'Follow-up',
        encounter_type: 'Office Visit',
        reason_for_visit: 'Chest pain evaluation',
        chief_complaint: 'Chest pain'
      }
    });
  };

  const handlePause = async () => {
    await pause();
    setPhase('paused');
  };

  const handleResume = async () => {
    await resume();
    setPhase('recording');
  };

  return (
    <div>
      <h3>Status: {sessionStatus}</h3>
      {sessionType === 'offline' && ( // added in v0.2.2
        <p>Session will sync when online</p>
      )}

      {sessionStatus === 'created' && phase === 'idle' && (
        <button type="button" onClick={handleStart}>Start Recording</button>
      )}

      {sessionStatus === 'created' && phase === 'recording' && (
        <>
          <button type="button" onClick={handlePause}>Pause</button>
          <button type="button" onClick={submit}>Finish & Submit</button>
        </>
      )}

      {sessionStatus === 'created' && phase === 'paused' && (
        <>
          <button type="button" onClick={handleResume}>Resume</button>
          <button type="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 client={client}>
      <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: 'FAMILY_MEDICINE' // Required for auto-registration
  });

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

  useEffect(() => {
    if (isLoggedIn && !sessionCreated) {
      create({ encounterId: 'your-encounter-id' });
    }
  }, [isLoggedIn, sessionCreated, create]);

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

  // Step 3: Manage recording
  // sessionStatus is only "created" | "submitted" | "completed" | "cancelled".
  // Track recording vs paused in local state (see AmbientSessionStatus type).
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType, // New in v0.2.2
    setSessionContext
  } = useAmbientSession({
    ambientSessionId: sessionId
  });
  const [phase, setPhase] = useState('idle'); // 'idle' | 'recording' | 'paused'

  async function handleStart() {
    await start();
    setPhase('recording');
    await setSessionContext({
      patient: { dob: '1980-01-15', sex: 'M' },
      provider: { specialty: 'FAMILY_MEDICINE', role: 'Attending Physician' },
      visit: {
        visit_type: 'Follow-up',
        encounter_type: 'Office Visit',
        reason_for_visit: 'Medication review'
      }
    });
  }

  async function handlePause() {
    await pause();
    setPhase('paused');
  }

  async function handleResume() {
    await resume();
    setPhase('recording');
  }

  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' && phase === 'idle' && (
        <button type="button" onClick={handleStart}>Start Recording</button>
      )}

      {sessionStatus === 'created' && phase === 'recording' && (
        <>
          <button type="button" onClick={handlePause}>Pause</button>
          <button type="button" onClick={submit}>Submit</button>
        </>
      )}

      {sessionStatus === 'created' && phase === 'paused' && (
        <>
          <button type="button" onClick={handleResume}>Resume</button>
          <button type="button" onClick={submit}>Submit</button>
        </>
      )}
    </div>
  );
}

Available tutorials

Headless Web SDK

Build a Headless Ambient Recorder

Use Headless hooks to sign in, create an ambient session, and control recording in a custom React UI.

20 minIntermediate

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

Get Started

Concepts & Feature Guides

API Reference

Resources

Headless Web SDK Quickstart

Prerequisites

Create your first Headless Web SDK Ambient session

Available tutorials

Build a Headless Ambient Recorder

Next steps

​Prerequisites

​Create your first Headless Web SDK Ambient session

​Available tutorials

​Build a Headless Ambient Recorder

​Next steps

Prerequisites

Create your first Headless Web SDK Ambient session

Available tutorials

Build a Headless Ambient Recorder

Next steps