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:May 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, session status, sessionType (online or offline), 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 displaying the current session state
isFetching for loading indicators and disabled states
ambientSessionId for identifying and tracking the active session

These values can be used to update labels, spinners, buttons, and workflow transitions in real time.

useAmbientSession hook

Usage

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

const {
  start,
  pause,
  resume,
  cancel,
  submit,
  setSessionContext,
  sessionStatus,
  isFetching,
  sessionType, // New in v0.2.2
  ambientSessionId,
  config,
  onAudioChunkAvailable,
} = useAmbientSession({...});

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:

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<Int16Array>) => 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. Resume later with resume(). 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 production pause and submit patterns in Session integration patterns. Learn how to handle errors in the Error handling guide.

​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

​Response type

​Code example

​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

Response type

Code example

Next steps