Quick summary
Ambient interoperability lets clinicians continue the same clinical note between the Mobile SDK, Web SDK, and Ambient APIs. Each product uses its own fields for the shared encounter values. In the Mobile SDK, use
SukiAmbientConstant.kEmrEncounterId and, for re-ambient workflows, SukiAmbientConstant.kSessionId.SukiAmbientConstant.kSessionId (maps to Ambient API encounter_id) and reuse it for every session on that note.
In the Mobile SDK, you can:
- Start an interoperable ambient session by passing
SukiAmbientConstant.kEmrEncounterId. - Continue in the Mobile SDK a clinical note that started in the Web SDK or Ambient APIs.
- Continue in the Web SDK or Ambient APIs a clinical note that started in the Mobile SDK.
- 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 callcreateSession, pass SukiAmbientConstant.kEmrEncounterId to identify the patient’s EMR or EHR encounter and make the note interoperable. For re-ambient workflows, pass SukiAmbientConstant.kSessionId (maps to Ambient API encounter_id) and reuse the same value for every session on that 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 APIambient_session_id. Use it for recording and session-level APIs. It is not theencounter_idyou pass askSessionId. kSessionId/encounter_id: Required for re-ambient workflows. Reuse the same value for every session on the note and asencounterIdforencounterContent.compositionId: The note id. Use it for note-level read APIs. It is notencounter_id.
sessionId.
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
Start the clinical note in the Mobile SDK, then open it in the Web SDK for review, edit, and submission. Use the shared encounter value through each product’s corresponding field.
Capture on Web, Continue on Mobile
Start the clinical note in the Web SDK, then continue it in the Mobile SDK. Use the shared encounter value through each product’s corresponding field.
Capture on Mobile, Continue with APIs
Start the clinical note in the Mobile SDK, then continue or retrieve it through Ambient APIs. Use the shared encounter values through each product’s corresponding fields.
Capture with APIs, Continue on Mobile
Start the clinical note through Ambient APIs, then continue it in the Mobile SDK. Use the shared encounter values through each product’s corresponding fields.
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 to make the note interoperable. For re-ambient workflows, passSukiAmbientConstant.kSessionId (Ambient API encounter_id) and reuse the same value for every session on that note.
1
Pass the EMR Encounter ID
Set
SukiAmbientConstant.kEmrEncounterId to the emr_encounter_id returned by the Ambient API.2
Pass encounter_id
Set
SukiAmbientConstant.kSessionId to the Ambient API encounter_id on the first session in a re-ambient workflow. Store and reuse the same value for every session on that note and for encounterContent. Do not use compositionId as this value.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
Use the shared encounter values through the target product’s corresponding fields. In the Mobile SDK, continue using
SukiAmbientConstant.kEmrEncounterId and SukiAmbientConstant.kSessionId. 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
AcreateSession 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:
- Read the
blockingSessionIdfrom the error. This value identifies the active ambient session and maps toambient_session_id. - 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.
- After the remote API call succeeds, retry
createSessionusing the sameSukiAmbientConstant.kEmrEncounterId.
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
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.
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
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
compositionIdas thenoteId. - The Ambient API
encounter_id(the same value you pass askSessionId) asencounterIdforencounterContent.
SukiStatus. These APIs use the same token provider configured for the ambient session APIs.
For
encounterContent, pass the Ambient API encounter_id (the same value you pass as 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 returnSukiStatus and do not create an offline session:
Other create failures can still follow the existing offline workflow. For more information, see Offline mode.
Available cookbooks
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 foremr_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.