Interoperability in the Web SDK

Learn how the Web SDK interoperates with other Suki products that support Ambient workflows

• Interoperability applies only to Ambient workflows. It is not supported for Dictation or Form filling workflows.
• Versions v3.2.0 and later support interoperability for the Headed 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 using the Mobile SDK, you could only continue or retrieve that session from the Mobile SDK.

With interoperability, you can create and access ambient sessions across different Suki products for the same patient encounter. The Ambient API returns emr_encounter_id. Any product that supports Ambient workflows uses this value through its own product-specific field. For the full Ambient API, Mobile SDK, and Web SDK field map, see Interoperable identifiers.

In the Web SDK, you can:

• Open a clinical note that started on Mobile SDK, Headless Web SDK, or Ambient APIs.
• Review, edit, and submit that shared note in the headed Web SDK UI.
• Start an ambient session in the Web SDK and continue or re-ambient it from another ambient product.

How interoperability works in the Web SDK

The core of ambient interoperability is a shared clinical note. When an ambient session originates in Ambient APIs, use the returned emr_encounter_id as encounter.identifier in the Web SDK.

You do not pass encounter_id to the Web SDK.

In the Web SDK, the encounter identifier you supply maps to emr_encounter_id:

Web SDK field	Maps to	Purpose
encounter.identifier	emr_encounter_id	The emr_encounter_id returned by the Ambient API. Accepts a UUID or non-UUID value, at most 36 characters.
encounter.patient	Patient profile in the Web SDK UI	Patient details required for a complete patient profile page.

The products do not share audio recordings. Instead, each ambient session contributes to the same clinical note.

If you do not provide an encounter identifier, Suki creates a normal ambient session in the Web SDK, but it remains independent and cannot participate in interoperability.

How to enable interoperability in the Web SDK

To enable interoperability in the Web SDK, set encounter.identifier to the shared encounter value for the patient visit. That value is the Ambient API emr_encounter_id. Other products use the same value through their own fields, for example SukiAmbientConstant.kEmrEncounterId in the Mobile SDK.

Some examples of how to handle interoperability in the Web SDK are:

• When a clinician starts ambient in the Mobile SDK, then opens the same note in the Web SDK for review, edit, and submission.
• When a clinician starts ambient through Ambient APIs, then opens the same note in the Web SDK.
• When a clinician starts ambient in the Web SDK, then continues the same note from the Mobile SDK or Ambient APIs.

In every case, keep encounter.identifier consistent for the patient visit in the Web SDK.

Pass the EMR encounter id on encounter.identifier only. Do not set emrEncounterId on ambientOptions. That field is not a supported partner setting and has no effect when an encounter identifier is present.

1. Pass a Stable Encounter Identifier

   Set encounter.identifier to the emr_encounter_id returned by the Ambient API. Use a UUID or non-UUID value, at most 36 characters.

2. Provide Patient Details

   Include patient fields on encounter.patient so the Web SDK can show the patient profile. If the session started on a headless product first, seed patient context with the Seed ambient session context API before opening the Web SDK.

3. Mount or Set the Encounter

   Pass the encounter through mount() or setEncounter() in JavaScript, or through the encounter prop on <SukiAssistant> in React. Refer to Create session for the full session setup.

4. Continue Across Products

   Continue using the same encounter.identifier in the Web SDK. Other SDKs use the identifiers through their own product-specific fields. Refer to Use interoperable ambient notes for the full workflow.

Identifier rules:

• encounter.identifier maps to emr_encounter_id and is stored as a varchar(36). Use a UUID or non-UUID value, at most 36 characters.
• Starting in v3.2.0, the Web SDK sends encounter.identifier as emr_encounter_id. The platform does not require UUID format.
• The same length limit applies when retrieving past notes for an encounter in the hosted UI.

Example

JavaScript

const encounter = {
  identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab", // maps to emr_encounter_id
  patient: {
    identifier: "905c2521-25eb-4324-9978-724636df3436",
    name: {
      use: "official",
      family: "Doe",
      given: ["John"],
    },
    birthDate: "1990-01-01",
    gender: "Male",
  },
};

sdkClient.mount({
  rootElement: document.getElementById("suki-root"),
  encounter,
});

Common integration patterns and use cases

Design Web SDK interoperability around the clinician’s journey for a single patient encounter. In the Web SDK, pass the emr_encounter_id returned by the Ambient API as encounter.identifier so the note is shared across products for the same patient visit.

The following patterns show common ways to use the Web SDK in interoperable ambient workflows:

Capture on Mobile, Review on Web

In the Mobile SDK, use the returned emr_encounter_id as SukiAmbientConstant.kEmrEncounterId. In the Web SDK, use that value as encounter.identifier to review, edit, and submit the note.

Capture with APIs, Review in Web SDK

Create the session and stream audio through Ambient APIs, then open the resulting note in the Web SDK for clinician review and submission.

Continue Documentation Across Products

Use the returned emr_encounter_id through each product’s corresponding field when clinicians continue documentation across products. For re-ambient workflows, the Web SDK continues the same clinical note using encounter.identifier (which maps to emr_encounter_id) without requiring encounter_id.

Keep Your Application in Sync

After clinicians edit the note in the Web SDK, retrieve the latest composition through the Ambient APIs so your application displays the current version.

Available cookbooks

Next steps

Create session - Configure the encounter and start an ambient session in the Web SDK.

Ambient interoperability - platform overview across ambient products.

Interoperable identifiers - Understand emr_encounter_id, encounter_id, and note_id.

Ambient interoperability FAQs - UUID requirement and other limitations.

Use interoperable ambient notes - end-to-end cross-modality workflow.