> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Ambient Session

> Configure `useAmbientSession` parameters and review returned actions, state, session context, and error behavior

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:

<ResponseField name="ambientSessionId" type="string" required>
  Pass the unique session identifier you received from the `useAmbient` hook. This links the recording to the session you created.
</ResponseField>

<ResponseField name="config.audioBatchSize" type="number">
  **Optional**: Configure the audio batch size for the `onAudioChunkAvailable` callback.
</ResponseField>

<ResponseField name="config.audio.deviceId" type="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](/headless-web-sdk/guides/hooks/select-microphone).
</ResponseField>

<ResponseField name="onAudioChunkAvailable" type="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.
</ResponseField>

<ResponseField name="onSessionTerminatedByPeer" type="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.
</ResponseField>

```tsx theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
type UseAmbientSessionParams = {
  ambientSessionId: string;
  config?: {
    audioBatchSize?: number;
    audio?: { // [!code ++:3] 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:

<ResponseField name="start" type="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.
</ResponseField>

<ResponseField name="pause" type="function: () => Promise<void>">
  Call this to pause recording temporarily. Resume later with `resume()`. Call this when the user clicks a "Pause" button.
</ResponseField>

<ResponseField name="resume" type="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.
</ResponseField>

<ResponseField name="cancel" type="function: () => Promise<void>">
  Call this to stop recording and cancel the session. Call this when the user clicks a "Cancel" or "Discard" button.
</ResponseField>

<ResponseField name="submit" type="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.
</ResponseField>

<ResponseField name="setSessionContext" type="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.
</ResponseField>

<ResponseField name="cancelRemote" type="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`.
</ResponseField>

<ResponseField name="endRemote" type="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.
</ResponseField>

```tsx theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
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:

<ResponseField name="sessionStatus" type="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](/headless-web-sdk/api-reference/types/ambient-session-status). Do not use this field alone for recording versus paused UI.
</ResponseField>

<ResponseField name="sessionType" type="'online' | 'offline' | null">
  Whether the session is online or offline. `null` until the SDK reports a session type.
</ResponseField>

### 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](/documentation/concepts/ambient-clinical-notes/note-sections) 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

```tsx theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
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;
    }>;
  };
};
```

<Note>
  * 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](/headless-web-sdk/guides/read-shared-ambient-notes#seed-patient-context-for-web-sdk-handoff).
</Note>

#### 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](/headless-web-sdk/guides/error-handling#context-update-errors-contextupdatefailed) for details.

## Next steps

<Icon icon="file-lines" iconType="solid" /> Choose which microphone ambient recording uses in [Select a microphone](/headless-web-sdk/guides/hooks/select-microphone).

<Icon icon="file-lines" iconType="solid" /> See working recording and microphone flows in [Ambient session examples](/headless-web-sdk/guides/hooks/ambient-session-examples).

<Icon icon="file-lines" iconType="solid" /> Refer to the [Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook) guide for recording lifecycle use cases.

<Icon icon="file-lines" iconType="solid" /> Learn how to handle `ContextUpdateFailed` and other errors in the [Error handling guide](/headless-web-sdk/guides/error-handling#context-update-errors-contextupdatefailed).

<Icon icon="file-lines" iconType="solid" /> Seed patient fields for Web SDK handoff in [Read shared ambient notes](/headless-web-sdk/guides/read-shared-ambient-notes#seed-patient-context-for-web-sdk-handoff).