Skip to main content
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.
  • 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 , 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.
  • 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 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.
Do not confuse these fields:
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.

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. 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.
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 the useAmbient 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 API encounter_id
  • emrEncounterId → Ambient API emr_encounter_id (required for interoperability)

Available cookbooks

AmbientHeadless Web SDK

Create an Interoperable Headless Session

Pass emrEncounterId on Headless create.

5 min
AmbientAPI

Share One Note Across Products

Share one note with emr_encounter_id.

5 min

Next steps

Refer to Handle ambient session conflicts for sessionAlreadyExists, 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.
Last modified on September 2, 2026