> ## 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.

# Manage Ambient Session

> Control session recording with `useAmbientSession`: start, pause, resume, optional microphone deviceId, cancel, submit audio, and track online or offline session status

<Callout title="Updates" color="orange" icon="bell">
  **Updated**

  * The `useAmbientSession` hook returns a `sessionType` property so you can tell whether the session is online or offline.
  * Ambient recording accepts an optional microphone `deviceId` through `config.audio` (**v0.3.1**). Pass a `MediaDeviceInfo.deviceId` from your own <Tooltip tip="Listing the microphones available in the browser so your app can let the user pick one. The Headless Web SDK does not list microphones for you." cta="View in Glossary" href="/Glossary/d">device enumeration</Tooltip>. Changing the mic while recording requires `pause()` then `resume()`. Refer to [Select a microphone](/headless-web-sdk/guides/hooks/select-microphone).
</Callout>

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    The `useAmbientSession` hook controls your audio recording workflow. Use it after creating a session with `useAmbient` to manage recording, pausing, and submitting audio.

    <br />

    <br />

    The hook provides methods to `start`, `pause`, `resume`, `cancel`, and `submit` recordings. Optionally pass `config.audio.deviceId` to select which microphone the recording uses. The hook returns session status so you can update your UI and provides real-time audio data through callbacks for building visualizations.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">September 2026</span>
  </div>
</div>

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. You can also pass an optional microphone **`deviceId`** so the recording uses a specific microphone when it starts or resumes.

### Configuration

Pass the **`ambientSessionId`** you received from **`useAmbient`** after **`session.isSuccess`** is `true` (refer to [Create ambient session](/headless-web-sdk/guides/hooks/ambient-hook)). Run the hook under **`PlatformClientProvider`**.
Refer to [Platform client and provider](/headless-web-sdk/api-reference/platform-client) for more information.

### Common use cases

<Steps>
  <Step title="Control the Recording Lifecycle" icon="play">
    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.
  </Step>

  <Step title="Select a Microphone for Ambient Capture" icon="microphone">
    Pass **`config.audio.deviceId`** with a `MediaDeviceInfo.deviceId` from your own `navigator.mediaDevices.enumerateDevices()` flow. Your app owns how you design and implement the microphone picker UI and device list. When `deviceId` is omitted, the recording uses the browser default microphone.

    The selected device is applied when recording starts or resumes. Changing `deviceId` while recording does not switch the microphone that is already in use. Call **`pause()`**, then **`resume()`**, after you update `config.audio.deviceId`. Refer to [Select a microphone](/headless-web-sdk/guides/hooks/select-microphone) guide for more details.
  </Step>

  <Step title="Attach Clinical Context to a Session" icon="clipboard">
    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](/headless-web-sdk/guides/hooks/ambient-session-config#session-context).
  </Step>

  <Step title="Support Online and Offline Session Flows" icon="signal">
    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.
  </Step>

  <Step title="Process Audio Waveform Data" icon="waveform">
    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.
  </Step>

  <Step title="Build Responsive Session Status UI" icon="display">
    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.
  </Step>

  <Step title="Resolve a Remote Session Conflicts" icon="triangle-exclamation">
    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](/headless-web-sdk/guides/handle-ambient-session-conflicts).
  </Step>

  <Step title="Handle Peer Session Termination" icon="bell">
    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.
  </Step>
</Steps>

## useAmbientSession hook

### Usage

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

```tsx theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
const {
  start,
  pause,
  resume,
  cancel,
  submit,
  setSessionContext,
  cancelRemote,
  endRemote,
  sessionStatus,
  sessionType,
} = useAmbientSession({
  ambientSessionId,
  config: {
    audioBatchSize: 5,
    audio: { deviceId: selectedMicrophoneId }, // [!code ++] New in v0.3.1
  },
  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. For parameter and return shapes refer to [Configuration](/headless-web-sdk/guides/hooks/ambient-session-config#configuration) and [What it returns](/headless-web-sdk/guides/hooks/ambient-session-config#what-it-returns) guides.

### How recording works

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

```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
flowchart TD
    A[Start recording] --> B[Recording active]
    B --> C{Pause or Submit?}
    C -->|Pause| D[Paused]
    C -->|Submit| E[Submitting]
    D -->|Resume| B
    E --> F[Complete]
    C -->|Cancel| G[Session cancelled]
    
    style A fill:#FFF394,stroke:#D4A017,color:#000000
    style B fill:#FFF394,stroke:#D4A017,color:#000000
    style E fill:#FFF394,stroke:#D4A017,color:#000000
    style F fill:#FFF394,stroke:#D4A017,color:#000000
    style D fill:#e3e0e0,stroke:#8b8a8a,color:#000000
    style G fill:#e3e0e0,stroke:#8b8a8a,color:#000000
```

## Next steps

<Icon icon="file-lines" iconType="solid" /> Configure options, session context, and return values in the [Configure ambient session](/headless-web-sdk/guides/hooks/ambient-session-config) guide.

<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" /> Learn how to handle errors in the [Error handling guide](/headless-web-sdk/guides/error-handling).

<Icon icon="file-lines" iconType="solid" /> Refer to [Handle ambient session conflicts](/headless-web-sdk/guides/handle-ambient-session-conflicts) when another product holds the active session.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.