Manage Ambient Session

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:September 2026

The useAmbientSession hook allows you to control the ambient recording workflow after you have an ambientSessionId. It exposes start, pause, resume, cancel, and submit, optional setSessionContext, cancelRemote, endRemote, session status, sessionType (online or offline), optional onSessionTerminatedByPeer, and optional real-time audio chunks for visualizations.

Configuration

Pass the ambientSessionId you received from useAmbient after session.isSuccess is true (refer to Create ambient session). Run the hook under PlatformClientProvider. Refer to Platform client and provider for more information.

Common use cases

Control the Recording Lifecycle

Use the recording control methods to match the behavior of your application’s recording experience:

start() to begin recording.
pause() to temporarily stop audio capture.
resume() to continue a paused recording.
cancel() to discard the current session.
submit() to finalize and submit the recording for processing.

Attach Clinical Context to a Session

Use setSessionContext() to associate patient, provider, and visit metadata with the active session.Call setSessionContext() after start() and before submit() to ensure the metadata is included with the session. For supported fields and examples, refer to Session context below.

Support Online and Offline Session Flows

Read sessionType to determine how the session is running:

"online" for real-time workflows.
"offline" for deferred or asynchronous processing workflows.

Use this value to conditionally render UI, messaging, or workflow behavior.

Process Audio Waveform Data

Use onAudioChunkAvailable to receive streamed audio chunks during recording. Audio data is returned as batched Int16Array chunks.Optionally configure config.audioBatchSize to control the batch size and frequency of audio chunk delivery.

Build Responsive Session Status UI

Use the returned session state values to drive UI behavior throughout the recording workflow:

sessionStatus for the server-side session lifecycle (for example created, submitted, completed).
sessionType for online versus offline messaging.

Keep a local UI phase (for example idle, recording, paused) for Start, Pause, and Resume. Do not use sessionStatus alone for recording versus paused.

Resolve Remote Session Conflicts

Use cancelRemote or endRemote with the blocking session id from a sessionAlreadyExists create error when another Suki product holds the active ambient session. Then retry create. Refer to Handle ambient session conflicts.

Handle Peer Session Termination

Pass onSessionTerminatedByPeer so your UI can clear recording controls when another product cancels or ends the live session. Update UI only. Do not call local cancel, submit, or remote clear APIs for that direction.

useAmbientSession hook

Usage

Call useAmbientSession with an object that includes ambientSessionId and optional config, onAudioChunkAvailable, and onSessionTerminatedByPeer.

const {
  start,
  pause,
  resume,
  cancel,
  submit,
  setSessionContext,
  cancelRemote,
  endRemote,
  sessionStatus,
  sessionType,
} = useAmbientSession({
  ambientSessionId,
  config: { audioBatchSize: 5 },
  onAudioChunkAvailable: (chunks) => {
    // Optional: draw a waveform from Int16Array batches
  },
  onSessionTerminatedByPeer: ({ sessionId, reason }) => {
    // Update UI only
  },
});

Returns

The hook returns control methods, session status, sessionType, and related fields. Parameter and return shapes are documented under Configuration and What it returns.

How recording works

Pass the session ID: Provide the ambientSessionId from useAmbient.
Configure options: Optionally set config.audioBatchSize and onAudioChunkAvailable for real-time audio batches.
Use the controls: Call start, pause, resume, cancel, and submit to move through the lifecycle your UI needs.

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.

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
  };
  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. 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. 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>). 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: {
        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. 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.

Get Started

Concepts & Feature Guides

API Reference

Resources

Manage Ambient Session

Configuration

Common use cases

useAmbientSession hook

Usage

Returns

How recording works

Configuration

What it returns

Actions (methods)

State (data)

Session context

What is session context?

When to use it

Session context structure

Success and errors

Code example

Available tutorials

Build a Headless Ambient Recorder

Next steps

​Configuration

​Common use cases

​useAmbientSession hook

​Usage

​Returns

​How recording works

​Configuration

​What it returns

​Actions (methods)

​State (data)

​Session context

​What is session context?

​When to use it

​Session context structure

​Success and errors

​Code example

​Available tutorials

​Build a Headless Ambient Recorder

​Next steps

Configuration

Common use cases

useAmbientSession hook

Usage

Returns

How recording works

Configuration

What it returns

Actions (methods)

State (data)

Session context

What is session context?

When to use it

Session context structure

Success and errors

Code example

Available tutorials

Build a Headless Ambient Recorder

Next steps