Skip to main content
Quick summary
Clear a blocking remote ambient session with cancelRemote or endRemote when create fails with sessionAlreadyExists, then retry create. Keep your UI in sync with onSessionTerminatedByPeer when another Suki product cancels or ends the live session.
  • These flows apply only to Ambient interoperability for Headless Web SDK. Dictation and Form filling do not support interoperability.
  • Use @suki-sdk/platform and @suki-sdk/platform-react v0.3.0 or later.
  • Pass emrEncounterId on create so the note is interoperable. Refer to Ambient interoperability.
Only one active ambient session can exist for the same provider and EMR encounter across Suki products.
  • If session.create() fails because another Suki product already has an active session for the same provider and EMR encounter, clear the existing session with cancelRemote or endRemote, then retry the create request.
  • If another Suki product cancels or ends the session currently active in your Headless Web SDK app, the SDK clears its local session state and calls onSessionTerminatedByPeer.

Resolve an active session conflict

When another Suki product already has an active ambient session for the same provider and EMR encounter, session.create() fails with:
  • HTTP status: 409
  • reason: sessionAlreadyExists
  • blockingSessionId: The ID of the active session blocking the create request, returned in error.additionalProperties
To resolve the conflict:
  1. Catch the session.create() error and check whether reason === "sessionAlreadyExists".
  2. Read the blockingSessionId from error.additionalProperties.
  3. Call cancelRemote or endRemote for the blocking session.
  4. After the remote operation succeeds, retry session.create() with the same emrEncounterId and encounterId.
The Headless Web SDK does not require a delay between a successful cancelRemote or endRemote call and the retry of session.create().
The sessionAlreadyExists conflict applies only when session.create() runs online. If the first ambient session is fully offline, another Suki product can start a session for the same EMR encounter without receiving a conflict error.

Conflict error fields

When create fails with a remote session conflict, the thrown PlatformError includes the following fields.
"sessionAlreadyExists"
Identifies a remote session conflict. Check this value before calling cancelRemote or endRemote.
string
Human-readable conflict message from the platform. Use this for UI copy when present.
object
Structured conflict details. Some JSDoc comments refer to metadata. The runtime field is additionalProperties.

Remote recovery actions

cancelRemote and endRemote are available on useAmbient and useAmbientSession. Pass the blocking session id from the conflict error. Do not pass your local ambientSessionId unless that id is the blocking session.
(params: { ambientSessionId: string }) => Promise<void>
Discards the blocking remote session without generating a note from that session. Pass { ambientSessionId: blockingSessionId }.
(params: { ambientSessionId: string }) => Promise<void>
Ends the blocking remote session so any audio already captured can be processed. Pass { ambientSessionId: blockingSessionId }.
If cancelRemote fails, the error reason is cancelRemoteSessionFailed. If endRemote fails, the error reason is endRemoteSessionFailed. Refer to Error handling.

Code example for clearing a remote session conflict

React
  • Use cancelRemote when you want to discard the blocking session.
  • Use endRemote when you want the blocking session to end and process any audio already captured.

What happens when another Suki product ends the live session

If another Suki product cancels or ends the ambient session that is currently active in your Headless Web SDK app, the SDK clears local session state before it notifies your app. The SDK:
  • Stops the microphone.
  • Deletes local audio and IndexedDB metadata for the session.
  • Resets the stream.
  • Sets local status to submitted when the termination reason is ENDED, or to cancelled otherwise.
Then it calls onSessionTerminatedByPeer with { sessionId, reason }. In that callback, update your recording UI to match the new session status. The Headless Web SDK already stopped the microphone and cleared local session state, so do not call cancel(), submit(), cancelRemote(), or endRemote().

Remote session end callback

Pass onSessionTerminatedByPeer to useAmbientSession when you need to keep recording UI in sync after another Suki product cancels or ends the live session.
function (payload: { sessionId: string; reason: string }) => void
Optional: Called after another Suki product cancels or ends the live session. Update your recording UI to match the new session status. Do not call cancel(), submit(), cancelRemote(), or endRemote(). The SDK already cleared local mic, stream, and session state.

Code example for handling a remote session end

React

Available cookbooks

AmbientHeadless Web SDK

Create an Interoperable Headless Session

Pass emrEncounterId and clear conflicts.

5 min
AmbientAPI

Clear a Remote Session Conflict

End remote session, then retry.

5 min

Next steps

Refer to Ambient interoperability to enable create with emrEncounterId and encounterId. Refer to Read shared ambient notes for useGetEncounterInfo and patient context for Web SDK handoff. Refer to Create ambient session for useAmbient, including cancelRemote and endRemote on create. Refer to Manage ambient session for onSessionTerminatedByPeer, cancelRemote, and endRemote on the live session. Refer to Error handling for sessionAlreadyExists, cancelRemoteSessionFailed, and endRemoteSessionFailed.
Last modified on September 2, 2026