Full Code Example

Full code example for useAmbientSession recording controls, plus Headless Ambient tutorials and next steps

The following example shows how to build a recording interface with start, pause, resume, and submit controls. The UI updates based on sessionStatus to show the appropriate buttons at each stage. Pass selectedMicrophoneId when you want a specific microphone. Leave it out to use the browser default.

React

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

export const Recorder = ({
  sessionId,
  selectedMicrophoneId, // New in v0.3.1
}) => {
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType, // New in v0.2.2
    setSessionContext
  } = useAmbientSession({
    ambientSessionId: sessionId,
    config: selectedMicrophoneId // New in v0.3.1
      ? { audio: { deviceId: selectedMicrophoneId } }
      : undefined,
    onAudioChunkAvailable: (chunk) => {
      // Optional: Pass chunk to a waveform visualizer
      drawWaveform(chunk);
    }
  });

  // Set context immediately after starting for better note quality
  const handleStart = async () => {
    await start();
    // Send patient and visit context to improve note generation
    await setSessionContext({
      patient: {
        patient_id: '905c2521-25eb-4324-9978-724636df3436',
        name: {
          use: 'official',
          family: 'Doe',
          given: ['John'],
        },
        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'
      }
    });
  };

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

      <div className="button-group">
        {/* Start Button */}
        {sessionStatus === 'created' && (
          <button onClick={handleStart}>Start Recording</button>
        )}

        {/* Pause/Resume Toggles - Add your own state tracking for recording/paused */}
        <button onClick={pause}>Pause</button>
        <button onClick={resume}>Resume</button>

        {/* Finalize Button */}
        <button onClick={submit}>
          Finish & Submit
        </button>
      </div>
    </div>
  );
};

Always call setSessionContext to provide patient and encounter details. This context helps the AI understand the clinical scenario and generates significantly higher quality clinical notes.

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

Learn production pause and submit patterns in Session integration patterns.

Call startAmbientSession and resumeAmbientSession with microphone options in Platform client and provider.

Learn how to handle errors in the Error handling guide.

Refer to Handle ambient session conflicts and Read shared ambient notes for remote conflict handling, remote session end handling, and shared note reads.