Skip to main content
UpdatedThe useAmbientSession hook now returns a sessionType property. This helps you determine whether the session is an online or offline session.
Quick Summary
The useAmbientSession hook controls your audio recording workflow. Use it after creating a session with useAmbient to manage recording, pausing, and submitting audio.

The hook provides methods to start, pause, resume, cancel, and submit recordings. It returns session status so you can update your UI and provides real-time audio data through callbacks for building visualizations.
Last updated:January 2026

​
Overview

The useAmbientSession hook controls your audio recording workflow. Use it after creating a session with useAmbient to manage recording, pausing, and submitting audio. What it does:
  • Provides methods to control recording: Start, pause, resume, cancel, and submit audio
  • Returns session status: Shows the current state of your session
  • Provides real-time audio data: Gives you access to audio chunks through callbacks for building visualizations
  • Manages session context: Lets you send patient and visit information to improve note quality

​
How It Works

The hook works in three steps:
  1. Pass the session ID - Provide the ambientSessionId you got from useAmbient
  2. Configure options - Optionally set up audio batch size and callbacks for real-time audio data
  3. Use the controls - Call methods like start(), pause(), and submit() to control recording
The hook returns control methods and status information you use to update your UI and manage the recording lifecycle. 
const {
  start,
  pause,
  resume,
  cancel,
  submit,
  setSessionContext,
  sessionStatus,
  isFetching,
  sessionType, // New in v0.2.2
  ambientSessionId,
  config,
  onAudioChunkAvailable,
});

​
Configuration

Configure the hook with these parameters:
​
ambientSessionId
string
required
Pass the unique session identifier you received from the useAmbient hook. This links the recording to the session you created.
​
config.audioBatchSize
number
Optional: Configure the audio batch size for the onAudioChunkAvailable callback.
​
onAudioChunkAvailable
function (audioChunk: Array<Int16Array>) => void
Optional: Provide a callback function that receives audio chunks as they become available. The SDK calls this function whenever a batch of audio data is ready. Use this to draw real-time waveforms, visualizers, or other audio visualizations in your UI.
type UseAmbientSessionParams = {
  ambientSessionId: string;
  config?: {
    audioBatchSize?: number
  };
  onAudioChunkAvailable?: (audioChunk: Array<Int16Arary>) => void;
}

​
What It Returns

The hook returns control methods and status information you use to manage recording and update your UI.

​
Actions (Methods)

Use these methods to control the recording workflow:
​
start
function: () => Promise<void>
Call this to begin recording audio. Call this when the user clicks a “Start Recording” button.
​
pause
function: () => Promise<void>
Call this to pause recording temporarily. You can resume later. Call this when the user clicks a “Pause” button.
​
resume
function: () => Promise<void>
Call this to resume a paused recording. Call this when the user clicks a “Resume” button.
​
cancel
function: () => Promise<void>
Call this to stop recording and cancel the session. Call this when the user clicks a “Cancel” or “Discard” button.
​
submit
function: () => Promise<void>
Call this to finish recording and submit the session for note generation. Call this when the user clicks a “Finish” or “Submit” button.
​
setSessionContext
function: (context: SessionContext) => Promise<Response>
Call this to send patient, provider, and visit metadata to Suki. The function sends context information that helps Suki generate more accurate clinical notes. Call this after start() but before submit() for best results.
type UseAmbientSessionReturn = {
  start: () => Promise<void>;
  pause: () => Promise<void>;
  resume: () => Promise<void>;
  cancel: () => Promise<void>;
  submit: () => Promise<void>;
  setSessionContext: (sessionContext: SessionContext) => Promise<SessionContextResponse>;
  sessionStatus: 
    | "created"
    | "submitted"
    | "completed"
    | "cancelled";
  sessionType: "online" | "offline";
};

​
State (Data)

Use these values to control your UI and show the current session state:
​
sessionStatus
AmbientSessionStatus
Check this value to display the current session state in your UI. Common values: "created" (session ready to start), "submitted" (recording finished, processing), "completed" (note generated), and "cancelled" (session cancelled). Use this to show status messages, enable/disable buttons, or change UI states based on the session status.
​
isFetching
boolean
Check this flag to show a loading state while syncing session information. When true, the SDK is currently fetching session status from Suki’s backend. Display a loading indicator or disable actions while this is true.
​
sessionType
'online' | 'offline'
Use this value to determine whether the session is an online or offline session.

​
Session Context

The setSessionContext method lets you send patient, provider, and visit information to Suki. This context helps Suki’s AI generate more accurate and relevant clinical notes.

​
What Is Session Context?

Session context is metadata about the patient visit that improves note quality. Include:
  • Patient details: Date of birth, sex
  • Provider information: Specialty, role
  • Visit information: Visit type, encounter type, reason for visit, chief complaint
  • Clinical sections: LOINC codes for specific sections you want in the note
  • Diagnoses: Pre-existing or current diagnoses with codes and descriptions

​
When To Use It

Call setSessionContext after calling start() but before calling submit(). Providing context early helps the AI understand the clinical scenario and generate better notes.

​
Session Context Structure

type SessionContext = {
  patient?: {
    dob: string;
    sex: string;
  };
  provider?: {
    specialty: string;
    role?: string;
  };
  visit?: {
    visit_type?: string;
    encounter_type?: string;
    reason_for_visit?: string;
    chief_complaint?: string;
  };
  sections?: Array<{ loinc: string }>;
  diagnoses?: {
    values: Array<{
      codes: Array<{
        code: string;
        description: string;
        type: string;
      }>;
      diagnosisNote: string;
    }>;
  };
};

​
Response Type

type SessionContextResponse = Record<string, never>;
The setSessionContext method returns an empty object when successful. If an error occurs, it throws a ContextUpdateFailed error. See the Error Handling guide for details.

​
Code Example

This 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.
React
import { useAmbientSession } from '@suki-sdk/platform-react';

export const Recorder = ({ sessionId }) => {
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType, // New in v0.2.2
    setSessionContext
  } = useAmbientSession({
    ambientSessionId: sessionId,
    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: {
        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 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.

​
Next Steps

Learn how to handle errors in the Error Handling Guide guide.