Handle Ambient Session Conflicts

Clear a blocking remote ambient session with cancelRemote or endRemote, then retry create, and keep UI in sync when another Suki product ends the live session

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.

Last updated:September 2026

• 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.

reason · "sessionAlreadyExists"

Identifies a remote session conflict. Check this value before calling cancelRemote or endRemote.

message · string

Human-readable conflict message from the platform. Use this for UI copy when present.

additionalProperties · object

Structured conflict details. Some JSDoc comments refer to metadata. The runtime field is additionalProperties.

Hide properties

blockingSessionId · string · required

Ambient session id of the blocking remote session. Maps to Ambient API ambient_session_id. Pass this value to cancelRemote or endRemote.

blockingModality · string

Optional: Modality that owns the blocking session, for example "WEB_SDK" or "MOBILE".

elapsed · string

Optional: How long the blocking session has been active, for example "0s" or "5m".

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.

cancelRemote · (params: { ambientSessionId: string }) => Promise<void>

Discards the blocking remote session without generating a note from that session. Pass { ambientSessionId: blockingSessionId }.

endRemote · (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

import { useAmbient } from "@suki-sdk/platform-react";

export function CreateOrResolveConflict() {
  const { cancelRemote, endRemote, session } = useAmbient();

  // Reuse the same encounterId for every re-ambient session on this note.
  const existingEncounterId = "visit-note-1";
  const emrEncounterId = "6ec3920f-b0b1-499d-a4e9-889bf788e5ab";

  const createOrResolveConflict = async () => {
    try {
      await session.create({
        encounterId: existingEncounterId,
        emrEncounterId,
      });
    } catch (error) {
      if (
        error &&
        typeof error === "object" &&
        "reason" in error &&
        error.reason === "sessionAlreadyExists"
      ) {
        const blockingSessionId =
          "additionalProperties" in error &&
          error.additionalProperties &&
          typeof error.additionalProperties === "object" &&
          "blockingSessionId" in error.additionalProperties
            ? String(error.additionalProperties.blockingSessionId)
            : undefined;

        if (!blockingSessionId) {
          throw error;
        }

        // Discard the blocking session:
        await cancelRemote({ ambientSessionId: blockingSessionId });

        // Or end the blocking session so captured audio can be processed:
        // await endRemote({ ambientSessionId: blockingSessionId });

        await session.create({
          encounterId: existingEncounterId,
          emrEncounterId,
        });
        return;
      }

      throw error;
    }
  };

  return (
    <button type="button" onClick={() => void createOrResolveConflict()}>
      Create or resolve conflict
    </button>
  );
}

• 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.

onSessionTerminatedByPeer · 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.

Hide payload

sessionId · string

The ambient session id that was cancelled or ended remotely.

reason · string

Termination reason from the other product, for example "ENDED" or "CANCELLED". When the reason is "ENDED", local status becomes submitted. Otherwise local status becomes cancelled.

Code example for handling a remote session end

React

import { useAmbientSession } from "@suki-sdk/platform-react";

export function RemoteSessionEndListener({
  ambientSessionId,
}: {
  ambientSessionId: string;
}) {
  useAmbientSession({
    ambientSessionId,
    onSessionTerminatedByPeer: ({ sessionId, reason }) => {
      // reason: "ENDED" | "CANCELLED" | ...
      // Update recording UI. Do not call cancel, submit, cancelRemote, or endRemote.
      console.log("Remote session ended", sessionId, reason);
    },
  });

  return null;
}

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.