> ## 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.
# 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`](/web-sdk/api-reference/classes) or from [`useSuki()`](/web-sdk/api-reference/hooks) after you call `startAmbient()`. Refer to [Create session](/web-sdk/guides/ambient-implementation) 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.
```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#111827','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFFFF','tertiaryColor':'#F9FAFB','tertiaryTextColor':'#111827','tertiaryBorderColor':'#D1D5DB'}}}%%
flowchart TD
E[encounterId patient visit] --> N[noteId]
E --> S1[ambientSessionId]
E --> S2[ambientSessionId another recording]
S1 --> A[activeAmbientId while this session is active]
style E fill:#FFF394,stroke:#D4A017,color:#000000
style N fill:#FFF394,stroke:#D4A017,color:#000000
style S1 fill:#FFF394,stroke:#D4A017,color:#000000
style S2 fill:#FFF394,stroke:#D4A017,color:#000000
style A fill:#FFF394,stroke:#D4A017,color:#000000
```
| 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](/web-sdk/guides/note-management). |
| **`noteId`** | `onNoteSubmit` (React) and `note-submission:success` when the note completes successfully | Unique identifier for the generated note. Refer to [Note management](/web-sdk/guides/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](/web-sdk/api-reference/types/emitter-events) for the exact payload types. |
| **`activeAmbientId`** | [`SDKClientInstance`](/web-sdk/api-reference/classes), [`useSuki()`](/web-sdk/api-reference/hooks) | The ID of the currently active ambient session. Returns `null` if no session is active ([Classes](/web-sdk/api-reference/classes), [Hooks](/web-sdk/api-reference/hooks)). |
Refer to [Emitter events](/web-sdk/api-reference/types/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](/web-sdk/guides/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.
```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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);
});
```
```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useSuki, SukiProvider } from "@suki-sdk/react";
import { useEffect } from "react";
// useSuki must run under SukiProvider
const StatusListener = () => {
const { on } = useSuki();
useEffect(() => {
const unsubscribe = on("ambient:update", (flags) => {
console.log("Ambient in progress:", flags.isAmbientInProgress);
console.log("Ambient paused:", flags.isAmbientPaused);
});
return () => unsubscribe();
}, [on]);
return
App Content
;
};
export default function App() {
return (
);
}
```
## Status flags
Returns `true` if an ambient session is currently active (started and not cancelled or submitted).
Returns `true` if the ambient session is currently in a paused state.
## Available cookbooks