Session Status & Events

Track Ambient session status and lifecycle events (start, pause, resume, cancel, submit) with the Web SDK

The Web SDK sends real-time events so you can see ambient session status. The ambient:update event includes an ambientSessionId. That is the unique ID for that recording session.

Use it to follow the session lifecycle and when you report issues to support. You can also read the current session ID from activeAmbientId on SDKClientInstance or from useSuki() after you call startAmbient(). Refer to Create session for more detail.

Quick reference: IDs

The diagram below shows how different identifiers relate during an ambient session lifecycle in the Web SDK.

An encounter is the patient visit you supply at setup (encounter.identifier / encounterId). An ambient session is one recording for that visit (ambientSessionId / activeAmbientId). One encounter can include more than one ambient session and more than one note.

You start with the encounter ID for the visit. Each startAmbient() call creates an ambient session ID. activeAmbientId is that session’s ID while it is active, or null when no session is active. When note generation completes, noteId on onNoteSubmit / note-submission:success identifies the generated note. One encounter can have more than one note.

Field	Where you read it	What it is
encounterId	onNoteSubmit (React) and note-submission:success when the note completes successfully	Unique identifier for the patient visit (encounter) associated with the note. Refer to Note management.
noteId	onNoteSubmit (React) and note-submission:success when the note completes successfully	Unique identifier for the generated note. Refer to Note management.
ambientSessionId	ambient:update (along with isAmbientInProgress and isAmbientPaused), and in payloads for the ambient:start, ambient:pause, ambient:resume, ambient:cancel, and ambient:submit events	Unique ID for one ambient recording session. This is the same session identifier emitted across ambient events. Refer to Emitter events for the exact payload types.
activeAmbientId	SDKClientInstance, useSuki()	The ID of the currently active ambient session. Returns null if no session is active (Classes, Hooks).

Refer to Emitter events for the full event list and types.

Important:

encounterId is the visit. ambientSessionId and activeAmbientId identify one ambient recording. Do not treat them as interchangeable. encounterId comes back after the note completes (refer to Note management). It is the encounter you supplied at setup.

Lifecycle events

The Web SDK emits these events when the session state changes:

• ambient:start - Emitted when a new ambient session is started.
• ambient:pause - Emitted when the ambient session is paused.
• ambient:resume - Emitted when the ambient session is resumed.
• ambient:cancel - Emitted when the ambient session is cancelled.
• ambient:submit - Emitted when the ambient session is submitted.

JavaScript

sdkClient.on("ambient:update", (flags) => {
  console.log("Ambient in progress:", flags.isAmbientInProgress);
  console.log("Ambient paused:", flags.isAmbientPaused);
});
// lifecycle events supported by the Web SDK
sdkClient.on("ambient:start", ({ ambientSessionId }) => {
  // New in v2.0.4. Payload is { ambientSessionId }; refer to Emitter events.
  console.log("Ambient started:", ambientSessionId);
});

Status flags

isAmbientInProgress · boolean

Returns true if an ambient session is currently active (started and not cancelled or submitted).

isAmbientPaused · boolean

Returns true if the ambient session is currently in a paused state.

Available cookbooks

AmbientAPI

Poll Session Status Before Fetching Content

Poll until status is completed.

5 min

Next steps

Implement controlled sessions: Ambient implementation

Configure problem-based notes: PBC

Return to Ambient session overview