Quick summary
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.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
emrEncounterIdonsession.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.
- Keep recording UI in sync when another Suki product cancels or ends the live session. Refer to Handle ambient session conflicts.
- List shared notes and seed patient context for Web SDK review. Refer to Read shared ambient notes.
How Ambient interoperability works in the Headless Web SDK
When you callsession.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.
Product differences:
- Web SDK uses
encounter.identifierforemr_encounter_idonly. It does not takeencounter_idon create. - Mobile SDK uses
SukiAmbientConstant.kEmrEncounterIdandSukiAmbientConstant.kSessionId(wherekSessionIdmaps to Ambient APIencounter_id). - Headless Web SDK requires
encounterIdon every create, and uses optionalemrEncounterIdfor interoperability.
ambientSessionId.
Common integration patterns
Use these patterns when you build interoperable ambient workflows with the Headless Web SDK.Capture in Headless, Review on Web
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.Capture on Mobile, Continue in Headless
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.Capture in Headless, Continue with APIs
Start the clinical note in Headless, then continue or retrieve it through Ambient APIs using
emr_encounter_id, encounter_id, and note_id.Capture with APIs, Continue in Headless
Start the clinical note through Ambient APIs, then continue it in Headless with the same shared encounter values.
Resolve a Cross-Product Conflict
On
sessionAlreadyExists, read blockingSessionId from error.additionalProperties, cancel or end the blocking session, then retry create.Keep the UI in Sync on Remote End
Handle
onSessionTerminatedByPeer to update recording UI when another Suki product cancels or ends the live session.List Notes for the Visit
Call
useGetEncounterInfo with emrEncounterId, then use Ambient API note-level endpoints with noteId for content, context, and structured data.Seed Context for Web SDK Review
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. PassencounterId on every create, and reuse the same value for every re-ambient session on that note.
Create parameters
Pass these values tosession.create() on useAmbient.
string
required
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.string
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.boolean
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 theuseAmbient hook when session.isSuccess is true.
string | null
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.string | null
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
(params: { encounterId: string; emrEncounterId?: string; multilingual?: boolean }) => Promise<{ ambientSessionId: string; noteId: string }>
Creates a new ambient session. Pass
emrEncounterId when the note must be interoperable. Status flags on session update while the request runs.(params: { ambientSessionId: string }) => Promise<void>
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.(params: { ambientSessionId: string }) => Promise<void>
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.1
Pass the EMR Encounter ID
Set
emrEncounterId to the Ambient API emr_encounter_id. Use a UUID or non-UUID value, at most 36 characters.2
Pass encounterId
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.3
Store the Create Response
On success, store
ambientSessionId and noteId. Use ambientSessionId with useAmbientSession. Use noteId with note-level Ambient APIs. Refer to Read shared ambient notes.4
Continue Across Products
Pass the same shared encounter values through each product’s fields. In Headless, keep using
emrEncounterId and encounterId. Refer to 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.React
Wire mapping for create:
encounterId→ Ambient APIencounter_idemrEncounterId→ Ambient APIemr_encounter_id(required for interoperability)
Available cookbooks
AmbientHeadless Web SDK
Create an Interoperable Headless Session
Pass emrEncounterId on Headless create.
Next steps
Refer to Handle ambient session conflicts forsessionAlreadyExists, cancelRemote, endRemote, and remote session end handling.
Refer to Read shared ambient notes for useGetEncounterInfo, Ambient note APIs, and patient context for Web SDK handoff.
Refer to Create an interoperable Headless session for a short create and conflict recipe.
Refer to Create ambient session for useAmbient, create parameters, and create response fields.
Refer to Ambient interoperability for the platform overview across ambient products.