> ## 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.
# Create an Interoperable Headless Session
> Pass emrEncounterId on Headless create, store noteId, and clear a remote session conflict before retry
export const CbRecipeMeta = ({items = []}) =>
;
};
}
sidebar={{
tutorialHref: "/documentation/tutorials/headless-ambient-hooks",
apiHref: "/headless-web-sdk/guides/ambient-interoperability",
apiLabel: "View Interoperability Guide",
authSections: [
{
title: "Headless Web SDK",
text: "Authenticate PlatformClient before creating an ambient session. See",
href: "/headless-web-sdk/authentication",
linkLabel: "Headless authentication",
},
],
glance: [
{ label: "Product", value: "Ambient" },
{ label: "Surface", value: "Headless Web SDK" },
{ label: "Time", value: "~5 min" },
{ label: "Level", value: "Beginner" },
],
}}
>
## Problem
A Headless Web SDK ambient session is created, but the clinical note is not shared with Ambient APIs, Mobile SDK, or Web SDK. Without `emrEncounterId`, create still succeeds, but other Suki products cannot find or attach to the same note.
Interoperable ambient sessions require `emrEncounterId` on create, plus a reusable `encounterId` for re-ambient grouping. Store `ambientSessionId` and `noteId` from the create response, and handle `sessionAlreadyExists` conflicts before retry.
## Architecture
```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFFBDE','primaryTextColor':'#1C1C1C','primaryBorderColor':'#FFD147','lineColor':'#6F5410','secondaryColor':'#FFFDF5','tertiaryColor':'#FFEB94','fontSize':'13px'}}}%%
flowchart LR
A[Auth PlatformClient] --> B[session.create]
B --> C[Store IDs]
C --> D{Conflict}
D -->|No| E[Stream ambient]
D -->|sessionAlreadyExists| F[cancelRemote / endRemote]
F --> B
```
## Prerequisites
App wrapped with `PlatformClientProvider` and `useAuth` completed before calling ambient hooks.`@suki-sdk/platform-react` **v0.3.0** or later installed. See [Ambient interoperability](/headless-web-sdk/guides/ambient-interoperability).An `emrEncounterId` (UUID or non-UUID, at most **36 characters**) and a reusable `encounterId` for the visit note.
## Solution
On `session.create()`, pass an **`emrEncounterId`** (maps to `emr_encounter_id`; **UUID or non-UUID**, at most **36 characters**) and a reusable **`encounterId`** (maps to `encounter_id`). Store **`ambientSessionId`** and **`noteId`**. If create fails with `sessionAlreadyExists`, clear the blocking session with `cancelRemote` or `endRemote`, then retry.
```tsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useAmbient } from "@suki-sdk/platform-react";
export function CreateInteroperableHeadlessSession() {
const { cancelRemote, endRemote, session } = useAmbient();
const emrEncounterId = "6ec3920f-b0b1-499d-a4e9-889bf788e5ab";
const encounterId = "visit-note-1"; // reuse for every re-ambient on this note
async function createInteroperableSession() {
try {
const result = await session.create({
encounterId,
emrEncounterId,
});
// result.ambientSessionId → pass to useAmbientSession
// result.noteId → Ambient API note-level endpoints
return result;
} catch (error) {
return resolveConflictAndRetry(error);
}
}
async function resolveConflictAndRetry(error: unknown) {
if (
!error ||
typeof error !== "object" ||
!("reason" in error) ||
error.reason !== "sessionAlreadyExists"
) {
throw error;
}
const additionalProperties =
"additionalProperties" in error ? error.additionalProperties : undefined;
const blockingSessionId =
additionalProperties &&
typeof additionalProperties === "object" &&
additionalProperties !== null &&
"blockingSessionId" in additionalProperties
? String(additionalProperties.blockingSessionId)
: undefined;
if (!blockingSessionId) {
throw new Error(
"Conflict returned without blockingSessionId. Clear the active session from the owning product, then retry."
);
}
// Discard the blocking session:
await cancelRemote({ ambientSessionId: blockingSessionId });
// Or end it so captured audio can be processed:
// await endRemote({ ambientSessionId: blockingSessionId });
// No delay is required between a successful remote call and retry.
return session.create({
encounterId,
emrEncounterId,
});
}
return (
);
}
```
When `session.isSuccess` is `true`, `ambientSessionId` and `noteId` are also available on the hook return.
```tsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useGetEncounterInfo } from "@suki-sdk/platform-react";
export function ListEncounterNotes() {
const { data, isLoading, error } = useGetEncounterInfo({
emrEncounterId: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
});
if (isLoading) {
return
Loading encounter notes...
;
}
if (error) {
return
{error.message}
;
}
// data.notes[].note_id → use with Ambient note-level APIs
return (
{(data?.notes ?? []).map((note) => (
{note.note_id}
))}
);
}
```
Call `session.create({ encounterId, emrEncounterId })`. Interop requires `emrEncounterId`; reuse `encounterId` for re-ambient grouping on the same note.
Persist both IDs from the create result. Headless returns **`noteId`**, not `compositionId`. Use `noteId` with Ambient note-level APIs.
Read `error.additionalProperties.blockingSessionId`, then call `cancelRemote` or `endRemote` before retry. See [Handle ambient session conflicts](/headless-web-sdk/guides/handle-ambient-session-conflicts).
Use `useGetEncounterInfo` to list notes for the EMR encounter. Headless does not expose note content hooks, so call [Get note content](/api-reference/ambient-content/note-content) and related APIs after you have `noteId`.
## Try it
* **Create returns noteId and ambientSessionId**
After a successful create, both IDs should be available on the result and on the hook when `session.isSuccess` is `true`.
* **Notes appear for the EMR encounter**
`useGetEncounterInfo` with the same `emrEncounterId` should list `note_id` values you can pass to Ambient note-level APIs.
* **Conflicts clear before retry**
When another product holds an active session, `sessionAlreadyExists` should resolve after `cancelRemote` or `endRemote`, then a second create succeeds.
## Common mistakes
* Omit `emrEncounterId`. Create still succeeds, but the note is not interoperable.
* Pass the EMR visit id as `encounterId` only. Interop requires `emrEncounterId`. Reuse `encounterId` for re-ambient grouping.
* Expect create to return `compositionId`. Headless returns **`noteId`**.
* Read conflict details from `error.metadata`. Use **`error.additionalProperties.blockingSessionId`**.
* Call local `cancel()` or `submit()` when another Suki product cancels or ends the live session. Use `onSessionTerminatedByPeer` and update UI only.
## Related guides
* [Ambient interoperability](/headless-web-sdk/guides/ambient-interoperability)
* [Handle ambient session conflicts](/headless-web-sdk/guides/handle-ambient-session-conflicts)
* [Read shared ambient notes](/headless-web-sdk/guides/read-shared-ambient-notes)
## Related cookbooks
Share one note with emr\_encounter\_id.
End remote session, then retry.