Configure Ambient Session

Pass the session id from useAmbient, then optionally set which microphone to use, how often audio data is sent to your app, and what to do if another product ends the session.

Configuration

Configure the hook with these parameters:

string

required

Pass the unique session identifier you received from the useAmbient hook. This links the recording to the session you created.

number

Optional: Configure the audio batch size for the onAudioChunkAvailable callback.

string

Optional: MediaDeviceInfo.deviceId for a microphone. When set, the recording uses that microphone. When omitted or empty, the browser default microphone is used. Your app owns device enumeration and selection UI. Refer to Select a microphone.

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.

function (payload: { sessionId: string; reason: string }) => void

Optional: Called after another Suki product cancels or ends the live session. The SDK already stops the microphone, deletes local audio metadata, and resets the stream. Update your UI only. Do not call cancel(), submit(), cancelRemote(), or endRemote() for this direction.

type UseAmbientSessionParams = {
  ambientSessionId: string;
  config?: {
    audioBatchSize?: number;
    audio?: { // New in v0.3.1
      deviceId?: string;
    };
  };
  onAudioChunkAvailable?: (audioChunk: Array<Int16Array>) => void;
  onSessionTerminatedByPeer?: (payload: {
    sessionId: string;
    reason: string;
  }) => 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:

function: () => Promise<void>

Call this to begin recording audio. Applies config.audio.deviceId when capture starts. Call this when the user clicks a “Start Recording” button.

function: () => Promise<void>

Call this to pause recording temporarily. Resume later with resume(). Call this when the user clicks a “Pause” button.

function: () => Promise<void>

Call this to resume a paused recording. Applies the current config.audio.deviceId when capture starts again. Call this when the user clicks a “Resume” button.

function: () => Promise<void>

Call this to stop recording and cancel the session. Call this when the user clicks a “Cancel” or “Discard” button.

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.

function: (context: Omit<SessionContext, 'ambientSessionId'>) => Promise<void>

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. On success the promise resolves with no return value. On failure it throws.

function: (params: { ambientSessionId: string }) => Promise<void>

Cancels a remote ambient session that is blocking create in another modality. Pass the blocking session id from a sessionAlreadyExists create error, not the hook’s local ambientSessionId.

function: (params: { ambientSessionId: string }) => Promise<void>

Ends a remote ambient session that is blocking create in another modality so captured audio can be processed. Pass the blocking session id from a sessionAlreadyExists create error.

type UseAmbientSessionReturn = {
  start: () => Promise<void>;
  pause: () => Promise<void>;
  resume: () => Promise<void>;
  cancel: () => Promise<void>;
  submit: () => Promise<void>;
  setSessionContext: (sessionContext: Omit<SessionContext, "ambientSessionId">) => Promise<void>;
  cancelRemote: (params: { ambientSessionId: string }) => Promise<void>;
  endRemote: (params: { ambientSessionId: string }) => Promise<void>;
  sessionStatus: AmbientSessionStatus | null | undefined;
  sessionType: "online" | "offline" | null;
};

State (data)

Use these values to control your UI and show the current session state:

AmbientSessionStatus | null | undefined

Server-side session lifecycle. Common values:

"created" (ready to start)
"submitted" (recording finished, processing)
"completed" (note generated), and
"cancelled"

Can be null or undefined before the store has session state. For the full union, refer to AmbientSessionStatus. Do not use this field alone for recording versus paused UI.

'online' | 'offline' | null

Whether the session is online or offline. null until the SDK reports a session type.

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, optional patient_id, and optional structured name.
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;
    patient_id?: string;
    name?: {
      family?: string;
      given?: string[];
      suffix?: string[];
      use?: 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;
    }>;
  };
};

An empty name object is dropped and is not sent.
Name values are passed through as provided. The Headless Web SDK does not force normalization.
Web SDK handoff: If you capture audio in Headless but the clinician reviews the note in the Web SDK, send patient_id and structured name with setSessionContext. Suki uses those fields to fill in the patient header in the Web SDK. See Seed patient context for Web SDK handoff.

Success and errors

On success, setSessionContext resolves with no return value (Promise<void>). PlatformClient.setSessionContext throws AmbientSessionError with code: "ContextUpdateFailed". setSessionContext from useAmbientSession throws that failure as a string. See the Error handling guide for details.

Next steps

Select a microphone Ambient session examples Manage ambient session - Guide for recording lifecycle use cases. Error handling guide Read shared ambient notes

Get Started

Concepts & Feature Guides

API Reference

Resources

Configure Ambient Session

Configuration

What it returns

Actions (methods)

State (data)

Session context

What is session context?

When to use it

Session context structure

Success and errors

Next steps