Skip to main content
Quick summary
Ambient interoperability lets the Mobile SDK share one clinical note with Ambient APIs and the Web SDK for the same patient visit. Pass SukiAmbientConstant.kEmrEncounterId on createSession. Handle remoteSessionConflict with remote cancel or end, then retry. Listen for sessionTerminatedByPeer when another product ends the live session on this device. Use the note read APIs to list and fetch shared note content by composition id.
  • Interoperability applies only to Ambient workflows. It is not supported for Dictation or Form filling.
  • Only versions v2.7.0 and later support interoperability for the Mobile 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 , you can create and access ambient sessions across Ambient APIs, Mobile SDK, and Web SDK for the same patient encounter. Pass the same EMR encounter identifier so every session contributes to one shared clinical note. In the Mobile SDK, you can:
  • Start an interoperable ambient session by passing SukiAmbientConstant.kEmrEncounterId.
  • Clear a blocking session on another Suki product, then retry create.
  • React when another Suki product cancels or ends the live session.
  • List and read shared notes for an EMR encounter.

How Ambient interoperability works in the Mobile SDK

When you call createSession and pass SukiAmbientConstant.kEmrEncounterId, the Mobile SDK associates the session with the patient’s EMR or EHR encounter. If a shared clinical note already exists for that encounter, the session is added to that note. Otherwise, Suki creates a new shared clinical note. The table below shows how Mobile SDK identifiers map to the corresponding Ambient API fields.
Keep these identifiers separate:
  • Create response sessionId: Maps to Ambient API ambient_session_id. Use it for recording and session-level APIs. It is not the Session Group ID.
  • Session Group ID: Maps to Ambient API encounter_id. Pass it with SukiAmbientConstant.kSessionId when you create or re-ambient. Pass the same value as encounterId to encounterContent.
  • compositionId: The note id. Use it for note-level read APIs. It is not the Session Group ID.
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 sessionId.
If you omit SukiAmbientConstant.kEmrEncounterId on createSession, the Mobile SDK still creates an ambient session, but the clinical note is not shared with other Suki products.

Common integration patterns

Below are some common integration patterns for ambient interoperability that you can use as a reference for your implementation while building your ambient workflows using the Mobile SDK.

Capture on Mobile, Review on Web

Create the ambient session with kEmrEncounterId, then open the same note in the Web SDK for review, edit, and submit.

Resolve a Cross-Device Conflict

On remoteSessionConflict, cancel or end the blocking session with blockingSessionId, then retry create.

Keep the UI in Sync on Peer End

Handle sessionTerminatedByPeer to clear recording UI when another product ends the live session.

List Notes for the Visit

Call listEncounterNotes with the EMR encounter id, then call getNoteContent(noteId:) (or context / structured data) with compositionId as noteId.

How to enable interoperability in the Mobile SDK

Pass a stable EMR encounter UUID for every ambient session that belongs to the same patient visit. Pass the Session Group ID (encounter_id) with SukiAmbientConstant.kSessionId when you create or re-ambient the same clinical note.
1

Pass the EMR Encounter ID

Set SukiAmbientConstant.kEmrEncounterId to your EMR or EHR encounter UUID for the visit. Use the same value as emr_encounter_id on Ambient APIs and as encounter.identifier in the Web SDK.
2

Pass the Session Group ID

Set SukiAmbientConstant.kSessionId to the Session Group ID (encounter_id) when you create or re-ambient the session. Store that same value for later creates and for encounterContent. Do not use compositionId as the Session Group ID.
3

Store the Create Response

On success, store sessionId and compositionId when present. Use sessionId for recording controls and session-level content APIs. Use compositionId as noteId for note-level read APIs.
4

Continue Across Products

To continue or re-ambient from Ambient APIs or the Web SDK, reuse the same EMR encounter id and Session Group ID. For more information, see Use ambient across modalities.

Code example for creating an interoperable session

Use the following code example to create an interoperable ambient session in the Mobile SDK.
Swift

How to handle a remote session conflict

A createSession request fails with SukiAmbientCoreError.remoteSessionConflict(blockingSessionId:) when another Suki product already has an active ambient session for the same provider and EMR encounter. To create a new session:
  1. Read the blockingSessionId from the error. This value identifies the active ambient session and maps to ambient_session_id.
  2. Clear the blocking session by calling one of the following APIs with the blockingSessionId:
    • cancelRemoteAmbientSession(ambientSessionId:onCompletion:) to cancel the remote session and discard it.
    • endSessionRemotely(sessionId:onCompletion:) to end the remote session so any audio already captured can be processed.
  3. After the remote API call succeeds, retry createSession using the same SukiAmbientConstant.kEmrEncounterId.
The SDK does not require a delay between the successful remote operation and retrying createSession.
remoteSessionConflict only applies when create runs online. If the first ambient session is fully offline, another Suki product can still start a session for the same EMR encounter, and you may not receive a conflict error.

Code example for handling a remote session conflict

Use the following code example to handle a remote session conflict in the Mobile SDK.
Swift
  • remoteSessionConflict is a server-side interoperability conflict. It can occur when you pass an EMR encounter id and another Suki product already holds the active ambient session.
  • sessionInProgress is a local conflict only. An ambient session is already active on the current device. End or cancel that session locally before calling createSession again. An EMR encounter id is not required for this case.
  • Use cancelRemoteAmbientSession when you want to discard the blocking session. Use endSessionRemotely when you want the blocking session to end and process any audio already captured.

What happens when a peer terminates the live session

If another Suki product cancels or ends the ambient session that is currently live in your app, the SDK tears down the session locally before it notifies your app. The SDK:
  • Stops the microphone
  • Deletes local audio for the session
  • Closes the stream
  • Clears the local session state
Then it delivers SessionEvent.sessionTerminatedByPeer(reason:) with .cancelled or .ended. Update your UI only. Do not call local end(), cancel(), or clear(). Teardown is already complete. Do not call cancelRemoteAmbientSession or endSessionRemotely for this direction.

Code example for handling a peer end event

Use the following code example to handle a peer end event in the Mobile SDK.
Swift
For more information, see Session events and delegates.

How to read shared notes

To list or retrieve clinical notes shared across Suki products, use the note read APIs. Depending on the API, pass one of the following:
  • An EMR encounter id
  • A compositionId as the noteId
  • A Session Group ID as encounterId for encounterContent
All of these APIs are asynchronous, and their completion handlers are invoked on the main queue. Errors are returned as generic or gRPC errors, not SukiStatus. These APIs use the same token provider configured for the ambient session APIs.
For encounterContent, pass the Session Group ID (encounter_id / kSessionId). Do not pass the EMR encounter id.

Code example for reading shared notes

Use the following code example to read shared notes in the Mobile SDK.
Swift
status(for:), content(for:), transcript(for:), and getStructuredData(for:) still take sessionId and return status or content for a single ambient session. Use the note read APIs above when you list or retrieve clinical notes shared across Suki products. For full method details and signatures, see Session status and content retrieval.

Create errors that do not fall back to offline

These create failures return SukiStatus and do not create an offline session: Other create failures can still follow the existing offline workflow. For more information, see Offline mode.

Next steps

Refer to Create ambient session for session info parameters and create response fields. Refer to Ambient interoperability for the platform overview across ambient products. Refer to Interoperable identifiers for emr_encounter_id, encounter_id, and composition_id. Refer to Use interoperable ambient notes for the end-to-end cross-modality workflow. Refer to Web SDK interoperability when the shared note opens in the headed Web SDK. Refer to Seed patient context for Web SDK if a Mobile or API session will open later in the headed Web SDK.
Last modified on July 24, 2026