> ## 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. # Headless Web SDK Ambient Interoperability > Share one clinical note across Headless Web SDK, Mobile SDK, Web SDK, and Ambient APIs by passing emrEncounterId on session.create
Ambient interoperability lets clinicians continue the same clinical note across the Headless Web SDK, Mobile SDK, Web SDK, and Ambient APIs. In the Headless Web SDK, pass `emrEncounterId` on `session.create()` so the note is shared. Pass and reuse `encounterId` for every re-ambient session on that note.
* Interoperability applies only to **Ambient workflows**. It is not supported for Dictation or Form filling. * Versions **`v0.3.0`** and later of `@suki-sdk/platform` and `@suki-sdk/platform-react` support interoperability for the Headless Web SDK. Ambient interoperability lets you use multiple Suki products that support ambient workflows with the same clinical note for a patient encounter. Before ambient interoperability, each ambient session belonged to the Suki product where it was created. For example, if you started a session with the Headless Web SDK, you could only continue or retrieve that session from the Headless Web SDK. With interoperability, you can create and access ambient sessions across Ambient APIs, Mobile SDK, Headless Web SDK, and Web SDK for the same patient encounter. Pass `emrEncounterId` to make the note interoperable. For re-ambient workflows, pass `encounterId` (maps to Ambient API `encounter_id`) and reuse it for every session on that note. In the Headless Web SDK, you can: * Start an interoperable ambient session by passing `emrEncounterId` on `session.create()`. * Continue a clinical note in Headless that started in the Mobile SDK, Web SDK, or Ambient APIs. * Continue a clinical note that started in Headless in another Suki product. * Clear a remote session conflict, then retry create. Refer to [Handle ambient session conflicts](/headless-web-sdk/guides/handle-ambient-session-conflicts). * Keep recording UI in sync when another Suki product cancels or ends the live session. Refer to [Handle ambient session conflicts](/headless-web-sdk/guides/handle-ambient-session-conflicts#what-happens-when-another-suki-product-ends-the-live-session). * List shared notes and seed patient context for Web SDK review. Refer to [Read shared ambient notes](/headless-web-sdk/guides/read-shared-ambient-notes). ## How Ambient interoperability works in the Headless Web SDK When you call `session.create()`, pass `emrEncounterId` to identify the patient's EMR or EHR encounter and make the note interoperable. Pass `encounterId` on every create. For re-ambient workflows, reuse the same `encounterId` for every session on that note. The table below shows how Headless Web SDK identifiers map to the corresponding Ambient API fields. | Headless Web SDK | Ambient APIs | Available | Description | | ----------------------------------------------------- | ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`emrEncounterId`** | **`emr_encounter_id`** | Passed to `session.create()` | Identifies the patient encounter in your EMR or EHR. Required to enable ambient interoperability. Accepts a **UUID or non-UUID** value, at most **36 characters**. | | **`encounterId`** | **`encounter_id`** | Passed to `session.create()` (required) | Groups re-ambient sessions for the same note. Reuse the same value for every session on that note. | | **`ambientSessionId`** (create response / hook state) | **`ambient_session_id`** | Returned on every successful create | Identifies the current ambient session. Pass this value to `useAmbientSession`. | | **`noteId`** (create response / hook state) | **`note_id`** | Returned on every successful create | Identifies the shared clinical note. Store this value for note-level Ambient APIs. | | **`blockingSessionId`** (on `sessionAlreadyExists`) | **`ambient_session_id`** | Returned only when a remote session conflict occurs | Identifies the active ambient session running in another Suki product. Pass this value to `cancelRemote` or `endRemote` before retrying create. Refer to [Handle ambient session conflicts](/headless-web-sdk/guides/handle-ambient-session-conflicts). | Do not confuse these fields: | Headless field | Maps to | Does not map to | | ---------------------- | ---------------------------------------------------- | ---------------------------------- | | **`emrEncounterId`** | Ambient API **`emr_encounter_id`** | Ambient API **`encounter_id`** | | **`encounterId`** | Ambient API **`encounter_id`** (re-ambient grouping) | Ambient API **`emr_encounter_id`** | | **`ambientSessionId`** | Ambient API **`ambient_session_id`** | Ambient API **`encounter_id`** | | **`noteId`** | Ambient API **`note_id`** | Ambient API **`encounter_id`** | **Product differences:** * **Web SDK** uses `encounter.identifier` for `emr_encounter_id` only. It does not take `encounter_id` on create. * **Mobile SDK** uses `SukiAmbientConstant.kEmrEncounterId` and `SukiAmbientConstant.kSessionId` (where `kSessionId` maps to Ambient API `encounter_id`). * **Headless Web SDK** requires `encounterId` on every create, and uses optional `emrEncounterId` for interoperability. Ambient interoperability shares the clinical note, not the audio recording. Each ambient session adds content to the same note. The audio for each session stays tied to that session's `ambientSessionId`. If you omit `emrEncounterId` on `session.create()`, the Headless Web SDK still creates an ambient session, but the clinical note is not shared with other Suki products. ## Common integration patterns Use these patterns when you build interoperable ambient workflows with the Headless Web SDK. Start the clinical note in the Headless Web SDK with `emrEncounterId`, then open it in the Web SDK for review, edit, and submission. Seed patient context before the Web SDK opens the note. Start the clinical note in the Mobile SDK, then continue it in Headless with the same EMR encounter id as `emrEncounterId` and the same re-ambient value as `encounterId`. Start the clinical note in Headless, then continue or retrieve it through Ambient APIs using `emr_encounter_id`, `encounter_id`, and `note_id`. Start the clinical note through Ambient APIs, then continue it in Headless with the same shared encounter values. On `sessionAlreadyExists`, read `blockingSessionId` from `error.additionalProperties`, cancel or end the blocking session, then retry create. Handle `onSessionTerminatedByPeer` to update recording UI when another Suki product cancels or ends the live session. Call `useGetEncounterInfo` with `emrEncounterId`, then use Ambient API note-level endpoints with `noteId` for content, context, and structured data. When the session may later open in the Web SDK, set patient identity and name on session context so the patient profile stays consistent. ## How to enable interoperability in the Headless Web SDK Pass a stable EMR encounter id to make the note interoperable. Use a **UUID or non-UUID** value, at most **36 characters**. Pass `encounterId` on every create, and reuse the same value for every re-ambient session on that note. ### Create parameters Pass these values to `session.create()` on `useAmbient`. Groups re-ambient sessions for the same clinical note. Maps to Ambient API **`encounter_id`**. Pass this on every create. Reuse the same value for every re-ambient session on that note. Do not pass the EMR visit id here, and do not use **`noteId`** as this value. **Optional**: EMR or EHR encounter id for the patient visit. Maps to Ambient API **`emr_encounter_id`**. Accepts a **UUID or non-UUID** value, at most **36 characters**. Required to enable ambient interoperability. Without this field, create still succeeds, but the note is not shared across Suki products. **Optional**: Enables multilingual ambient capture when supported for your integration. ### Create response and hook state After a successful create, read these values from the promise result or from the `useAmbient` hook when `session.isSuccess` is `true`. Identifies the current ambient recording session. Maps to Ambient API **`ambient_session_id`**. Pass this value to **`useAmbientSession`**. The hook value is `null` until create succeeds. Identifies the shared clinical note. Maps to Ambient API **`note_id`**. Store this value for note-level Ambient APIs. The hook value is `null` until create succeeds. This is **`noteId`**, not **`compositionId`**. ### Interop actions on useAmbient Creates a new ambient session. Pass **`emrEncounterId`** when the note must be interoperable. Status flags on `session` update while the request runs. Cancels a remote ambient session that is blocking create in another Suki product. Pass the **`blockingSessionId`** from a `sessionAlreadyExists` error. Available on `useAmbient` before a local session exists. For the full recovery flow, refer to [Handle ambient session conflicts](/headless-web-sdk/guides/handle-ambient-session-conflicts). Ends a remote ambient session that is blocking create in another Suki product so captured audio can be processed. Pass the **`blockingSessionId`** from a `sessionAlreadyExists` error. For the full recovery flow, refer to [Handle ambient session conflicts](/headless-web-sdk/guides/handle-ambient-session-conflicts). Set **`emrEncounterId`** to the Ambient API **`emr_encounter_id`**. Use a **UUID or non-UUID** value, at most **36 characters**. Set **`encounterId`** to the Ambient API **`encounter_id`** on every create. For re-ambient workflows, store and reuse the same value for every session on that note. Do not use **`noteId`** as this value. On success, store **`ambientSessionId`** and **`noteId`**. Use **`ambientSessionId`** with **`useAmbientSession`**. Use **`noteId`** with note-level Ambient APIs. Refer to [Read shared ambient notes](/headless-web-sdk/guides/read-shared-ambient-notes). Pass the same shared encounter values through each product's fields. In Headless, keep using **`emrEncounterId`** and **`encounterId`**. Refer to [Use ambient across modalities](/documentation/how-to/ambient-clinical-notes/use-ambient-across-modalities). ### Code example for creating an interoperable session Use the following code example to start an interoperable ambient session in the Headless Web SDK. ```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} import { useAmbient } from "@suki-sdk/platform-react"; export function StartInteroperableSession() { const { ambientSessionId, noteId, session, } = useAmbient(); // Reuse the same encounterId for every re-ambient session on this note. const existingEncounterId = "visit-note-1"; const startInteroperableSession = async () => { try { const result = await session.create({ encounterId: existingEncounterId, emrEncounterId: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab", multilingual: true, // optional }); // result.ambientSessionId and result.noteId // When session.isSuccess is true, ambientSessionId and noteId are also on the hook return. return result; } catch (error) { // Handle sessionAlreadyExists and other create errors. // See Handle ambient session conflicts. console.error(error); throw error; } }; return ( ); } ``` Wire mapping for create: * `encounterId` → Ambient API `encounter_id` * `emrEncounterId` → Ambient API `emr_encounter_id` (required for interoperability) ## Available cookbooks