Manage Ambient Session

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

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 device enumeration. Changing the mic while recording requires pause() then resume(). Refer to Select a microphone.

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). Run the hook under PlatformClientProvider. Refer to Platform client and provider for more information.

Common use cases

1. 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.
2. Select a Microphone for Ambient Capture

   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 guide for more details.

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

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

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

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

7. Resolve a 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.

8. 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,
    audio: { deviceId: selectedMicrophoneId }, // 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 and 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.

Next steps

Configure ambient session - Options, session context, and return values.

Select a microphone

Ambient session examples

Error handling guide

Handle ambient session conflicts - Another product holds the active session.