Build Headless Ambient Recorder

Use-case tutorial: Use Headless Web SDK hooks to authenticate, create an Ambient session, and control recording in React

What you will build

20 min | Intermediate

• A shared platform client for your React app.
• Sign-in with Headless auth.
• An ambient session for recording.
• Start, pause, resume, and submit controls, plus session context after start.
• Optional microphone selection with config.audio.deviceId (Headless Web SDK v0.3.1 or later).

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.

CopiedCopy promptOpen in Cursor

In this tutorial, you build a custom ambient recorder UI with the Headless Web SDK. You wrap the app with PlatformClientProvider, sign in with useAuth, create a session with useAmbient, and control recording with useAmbientSession.

By the end of this tutorial, you will have a React page that authenticates, creates an ambient session, and exposes start, pause, resume, and submit controls. You can optionally pass a microphone deviceId so the recording uses a specific microphone.

The Headless Web SDK is in beta. APIs and docs may change. Confirm package versions with your Suki contact before production use.

Prerequisites

Before you begin, make sure you have:

• Completed Partner onboarding.
• A React 18+ app that meets Headless Web SDK prerequisites.
• Staging partnerId and partnerToken values.

Headless Web SDK is for custom UIs. If you want the hosted ambient chrome, use the Web SDK ambient session tutorial instead.

Architecture

Project setup

1. Use a React 18+ app that meets Headless Web SDK prerequisites.
2. Install the required dependencies:.

# pnpm
pnpm add @suki-sdk/platform-react

# npm
npm install @suki-sdk/platform-react

3. Configure your credentials:.

   • Keep staging partnerId and partnerToken ready for sign-in.
   • Confirm beta expectations with your Suki contact before production use.

Tutorial steps

Work through each step in order. Read the explanation, review the code example, then continue to the next step. The full code example is available in the accordion below.

1. Create PlatformClient and Wrap the App

   Create one PlatformClient and wrap your app with PlatformClientProvider so hooks share the same client.

   Check: One PlatformClient is passed into PlatformClientProvider.

   If it fails: Wrap the tree with PlatformClientProvider and pass client={client}. Hooks do not work outside that provider.

   import { PlatformClient, PlatformClientProvider } from "@suki-sdk/platform-react";
   
   const client = new PlatformClient({
   env: "staging",
   enableDebug: true,
   logLevel: "error",
   });
   
   function App() {
   return (
   <PlatformClientProvider client={client}>
     <HeadlessAmbientRecorder />
   </PlatformClientProvider>
   );
   }
   
2. Authenticate with UseAuth

   Call useAuth under the provider. When autoRegister is true, pass providerName, providerOrgId, and providerSpecialty.

   Check: useAuth runs under the provider, and when autoRegister is true you pass providerName, providerOrgId, and providerSpecialty.

   import { useAuth } from "@suki-sdk/platform-react";
   
   function AuthGate({ children }) {
   const { isLoggedIn, isPending, error, login } = useAuth({
   partnerId: "YOUR_PARTNER_ID",
   partnerToken: "YOUR_PARTNER_TOKEN",
   autoRegister: true,
   loginOnMount: true,
   providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
   providerOrgId: "YOUR_ORG_ID",
   providerSpecialty: "FAMILY_MEDICINE", // Example specialty token — replace with yours
   });
   
   if (isPending) return <p>Signing in...</p>;
   if (error) return <p role="alert">{error.message}</p>;
   if (!isLoggedIn) {
   return (
     <button type="button" onClick={login}>
       Sign In
     </button>
   );
   }
   
   return children;
   }
   
3. Create an Ambient Session with UseAmbient

   Use useAmbient to create a session. Wait for isSuccess before you pass ambientSessionId into recording hooks.

   Check: isSuccess is true and ambientSessionId is set before you pass it into recording hooks.

   If it fails: Create the session only when the user is signed in and you have not already created a session for this screen.

   import { useEffect } from "react";
   import { useAmbient } from "@suki-sdk/platform-react";
   
   function SessionCreator({ onSessionReady }) {
   const {
   ambientSessionId,
   session: { create, isPending, isSuccess, error },
   } = useAmbient();
   
   useEffect(() => {
   create({ encounterId: 'your-encounter-id' });
   }, [create]);
   
   useEffect(() => {
   if (isSuccess && ambientSessionId) {
     onSessionReady(ambientSessionId);
   }
   }, [isSuccess, ambientSessionId, onSessionReady]);
   
   if (isPending) return <p>Creating session...</p>;
   if (error) return <p role="alert">{error.message}</p>;
   return null;
   }
   
4. Start, Pause, Resume, and Submit with UseAmbientSession

   Pass the session ID into useAmbientSession. After start(), call setSessionContext with patient and visit details to improve note quality. Track recording versus paused in local state. sessionStatus is only created, submitted, completed, or cancelled.

   Optionally pass config.audio.deviceId with a MediaDeviceInfo.deviceId from your own enumerateDevices() flow (v0.3.1 or later). Your app owns how you design and implement the microphone picker UI. Changing the microphone while recording does not switch the microphone that is already in use. Update deviceId in state, call pause(), then resume(). For the full enumerate-and-select sample, refer to Select a microphone guide.

   Check: You can start, pause, resume, and submit. sessionStatus is one of created, submitted, completed, or cancelled.

   If it fails: Changing config.audio.deviceId while recording does not switch the microphone already in use. Update deviceId in state, call pause(), then resume(). This path needs Headless Web SDK v0.3.1 or later.

   import { useState } from "react";
   import { useAmbientSession } from "@suki-sdk/platform-react";
   
   function Recorder({ sessionId, selectedMicrophoneId }) {
   const { start, pause, resume, submit, sessionStatus, setSessionContext } =
   useAmbientSession({
     ambientSessionId: sessionId,
     config: selectedMicrophoneId // New in v0.3.1
       ? { audio: { deviceId: selectedMicrophoneId } }
       : undefined,
   });
   // sessionStatus does not include "recording" or "paused". Track those locally.
   const [phase, setPhase] = useState<"idle" | "recording" | "paused">("idle");
   
   async function handleStart() {
   await start();
   setPhase("recording");
   await setSessionContext({
     // Example session context only — replace with real patient / visit metadata
     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() {
   // Keep config.audio.deviceId updated before resume if the user changed mics.
   await resume();
   setPhase("recording");
   }
   
   return (
   <div>
     <p>Status: {sessionStatus}</p>
     {sessionStatus === "created" && phase === "idle" && (
       <button type="button" onClick={handleStart}>Start</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>
   );
   }
   

   When an exact deviceId is unavailable or disconnected, start or resume fails with code StartSessionFailed or ResumeSessionFailed and reason AudioRecorderFailure. The SDK does not fall back to the browser default. Refresh devices and ask the user to choose again. In React, the thrown value is often a string from error.toString().

Full code example

React

// Headless Web SDK Ambient recorder tutorial (React, Beta)
// Copy this file into a React app, replace YOUR_* placeholders, then render <App />.
// Flow: PlatformClient → PlatformClientProvider(client) → useAuth → useAmbient create → useAmbientSession

import { useEffect, useState } from "react";
import {
  PlatformClient,
  PlatformClientProvider,
  useAuth,
  useAmbient,
  useAmbientSession,
} from "@suki-sdk/platform-react";

// sessionStatus values: "created" | "submitted" | "completed" | "cancelled"
// Track recording vs paused in local state (those are not sessionStatus values).

// 1) One shared client for the app lifetime (module scope, not inside a component).
const client = new PlatformClient({
  env: "staging",
  enableDebug: true,
  logLevel: "error",
});

function App() {
  return (
    // Pass the same client into the provider so all hooks share it.
    <PlatformClientProvider client={client}>
      <HeadlessAmbientRecorder />
    </PlatformClientProvider>
  );
}

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

  // 2) Sign in under the provider. When autoRegister is true, provider* fields are required.
  //    Use specialty enum tokens (for example FAMILY_MEDICINE), not display names.
  const { isLoggedIn, isPending: authPending, error: authError } = useAuth({
    partnerId: "YOUR_PARTNER_ID", // Required: from partner onboarding
    partnerToken: "YOUR_PARTNER_TOKEN", // Required
    autoRegister: true,
    loginOnMount: true,
    providerName: "Dr. Jane Smith", // Example only — replace with the provider's full name
    providerOrgId: "YOUR_ORG_ID", // Required when autoRegister is true
    providerSpecialty: "FAMILY_MEDICINE", // Example specialty token — replace with yours
  });

  // 3) Create an ambient session only after login, and only once.
  const {
    ambientSessionId,
    session: { create, isSuccess: sessionCreated, error: sessionError },
  } = useAmbient();

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

  useEffect(() => {
    // Wait for isSuccess before passing ambientSessionId into useAmbientSession.
    if (sessionCreated && ambientSessionId) {
      setSessionId(ambientSessionId);
    }
  }, [sessionCreated, ambientSessionId]);

  if (authPending) return <p>Signing in...</p>;
  if (authError) return <p role="alert">{authError.message}</p>;
  if (!isLoggedIn) return <p>Sign in required</p>;
  if (sessionError) return <p role="alert">{sessionError.message}</p>;
  if (!sessionId) return <p>Creating ambient session...</p>;

  return <Recorder sessionId={sessionId} />;
  // Optional: pass selectedMicrophoneId from your enumerateDevices() picker
  // return <Recorder sessionId={sessionId} selectedMicrophoneId={selectedMicrophoneId} />;
}

function Recorder({ sessionId, selectedMicrophoneId }) {
  // 4) Control recording for the session returned by useAmbient.
  const { start, pause, resume, submit, sessionStatus, setSessionContext } =
    useAmbientSession({
      ambientSessionId: sessionId,
      config: selectedMicrophoneId // New in v0.3.1
        ? { audio: { deviceId: selectedMicrophoneId } }
        : undefined,
    });
  // sessionStatus does not include "recording" or "paused". Track those locally.
  const [phase, setPhase] = useState<"idle" | "recording" | "paused">("idle");

  async function handleStart() {
    await start();
    setPhase("recording");
    // Call setSessionContext after start() and before submit() for better notes.
    await setSessionContext({
      // Example session context only — replace with real patient / visit metadata
      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() {
    // Keep config.audio.deviceId updated before resume if the user changed mics.
    await resume();
    setPhase("recording");
  }

  return (
    <div>
      <p>Status: {sessionStatus}</p>
      {sessionStatus === "created" && phase === "idle" && (
        <button type="button" onClick={handleStart}>
          Start
        </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>
  );
}

export default App;

Troubleshooting

Hooks Fail Outside Provider

Wrap the tree with PlatformClientProvider and pass client={client}.

Session Create Never Runs

Create only when signed in and you have not already created the session for this screen.

Beta API Surprises

Treat this SDK as beta; confirm package versions with your Suki contact.

Microphone DeviceId Not Applied Mid Recording

Changing config.audio.deviceId while recording does not switch the microphone that is already in use. Update the deviceId in your app state, call pause(), then resume(). Requires Headless Web SDK v0.3.1 or later. Refer to Select a microphone guide for more details.

Summary

In this tutorial, you:

• Wrapped the app with PlatformClientProvider.
• Signed in with useAuth and created a session with useAmbient.
• Controlled recording with useAmbientSession (start, pause, resume, and submit).
• Optionally selected a microphone with config.audio.deviceId (v0.3.1 or later).

Other tutorials

Continue with another end-to-end tutorial.