Create Session

Learn to create a session and implement controlled session management with the Suki Web SDK

Updated

From v2.2.0+, you can pass optional session-level metadata in ambientOptions to improve note generation. Put visit fields under visitContext (including visitType) and the provider role under providerContext. When you set visitContext.visitType, the Web SDK also uses it as the note title in the patient note list (see Note list titles).

Learn more in the AmbientOptions reference. These parameters are optional; omitting them does not break existing flows.

Ambient sessions created with the Web SDK are interoperable with Ambient APIs, Mobile SDK, and Headless Web SDK. The encounter identifier you supply maps to emr_encounter_id for cross-modality ambient workflows. Refer to Interoperability for Web SDK setup, and Ambient interoperability for the platform overview.

Before you can start recording audio and generating clinical notes using the Web SDK, you must create an ambient session. This guide shows you how to create a session and provide clinical context that helps Suki generate more accurate notes.

What will you learn?

In this guide, you will learn how to:

• Configure the SDK client with initialize() in JavaScript or init() from the useSuki() hook in React.
• Provide session context through mount() or the <SukiAssistant> component.
• Start an ambient session with startAmbient() and read the active session ID from activeAmbientId.

Create a controlled session

To create an ambient session with the Suki Web SDK, follow this three-step workflow:

1. Configure the Client

   You must first initialize the client to establish a connection.

   • JavaScript: Call initialize(options) to get back an SDKClientInstance.
   • React: Call init() from the useSuki() hook.
2. Provide Session Context

   You provide the encounter data and ambientOptions, such as patient details, note sections, and visit type, to improve note quality. Detailed context helps the Suki generate more accurate clinical notes.

   • JavaScript: Pass the context through sdkClient.mount().
   • React: Use the props on the <SukiAssistant> component.

   • patient.identifier is required; encounter.identifier is optional. Each must be a string at most 36 characters (varchar(36)). Longer strings can fail during composition or ambient workflows.

   • From Web SDK v3.2.0, if you set encounter.identifier, use a UUID. The Web SDK maps that value to emr_encounter_id for ambient interoperability and encounter note retrieval. Non-UUID values can break past-note loading even when ambient session start, pause, and submit still work.

3. Start the Session

   Once you have configured the client and context, you can start the ambient recording.

   • Start: Call startAmbient() on the client in JavaScript, or from the useSuki() hook in React.
   • Track: Read the active session ID from sdkClient.activeAmbientId, or from the useSuki() hook in React, to display the status of the current session.

Providing richer metadata in the ambientOptions ensures the Suki Web SDK has the necessary context to generate more accurate clinical notes.

The following example shows how to create an ambient session in JavaScript and React using the Suki Web SDK.

controlled.js

import { SukiAuthManager } from "@suki-sdk/core";
import { initialize } from "@suki-sdk/js";

let isSukiReady = false;

// Replace with your actual encounter data
const encounterDetails = {
  identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
  patient: {
    identifier: "905c2521-25eb-4324-9978-724636df3436",
    name: {
      use: "official",
      family: "Doe",
      given: ["John"],
      suffix: ["MD"],
    },
    birthDate: "1990-01-01",
    gender: "Male",
  },
};

const authManager = new SukiAuthManager({
  partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
  partnerToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Replace with your actual partner token
  providerName: "John Doe", // Replace with the full name of the provider
  providerOrgId: "1234", // Replace with the provider's organization ID
  providerSpecialty: "FAMILY_MEDICINE", // Replace with the provider's specialty
  environment: "production",
  loginOnInitialize: true,
  providerId: "1234567890", // Replace with the provider's ID
});

const sdkClient = initialize({
  authManager,
});

const unsubscribeInit = sdkClient.on("init:change", (isInitialized) => {
  if (isInitialized) {
    sdkClient.mount({
      rootElement: document.getElementById("suki-root"), // The root element to mount the SDK into
      encounter: encounterDetails,
      ambientOptions: {
        sections: [
          { loinc: "51848-0" },
          { loinc: "11450-4" },
          { loinc: "29545-1" },
        ],
        diagnoses: { // New in v2.1.2
          values: [
            {
              codes: [
                {
                  code: "I10",
                  description: "Essential hypertension",
                  type: "ICD10",
                },
              ],
              diagnosisNote: "Hypertension",
            },
          ],
        },
        // Optional: nest visit and provider context under visitContext / providerContext
        visitContext: {
          visitType: "ESTABLISHED_PATIENT", // New in v2.2.0
          encounterType: "AMBULATORY",
          reasonForVisit: "Follow-up for hypertension",
          chiefComplaint: "Headache",
        },
        providerContext: {
          providerRole: "PRIMARY/ATTENDING",
        },
      },
    });
  } else {
    isSukiReady = false; // Reset the ready state if initialization fails
  }
});

const unsubscribeReady = sdkClient.on("ready", () => {
  isSukiReady = true;
});

// Ambient session control functions
function startAmbient() {
  if (isSukiReady) {
    sdkClient.startAmbient();
  } else {
    console.error("Suki SDK is not ready yet.");
  }
}

function pauseAmbient() {
  if (isSukiReady) {
    sdkClient.pauseAmbient();
  } else {
    console.error("Suki SDK is not ready yet.");
  }
}

function resumeAmbient() {
  if (isSukiReady) {
    sdkClient.resumeAmbient();
  } else {
    console.error("Suki SDK is not ready yet.");
  }
}

function cancelAmbient() {
  if (isSukiReady) {
    sdkClient.cancelAmbient();
  } else {
    console.error("Suki SDK is not ready yet.");
  }
}

function submitAmbient() {
  if (isSukiReady) {
    sdkClient.submitAmbient();
  } else {
    console.error("Suki SDK is not ready yet.");
  }
}

// Attach event listeners to buttons
document.getElementById("start-ambient").addEventListener("click", startAmbient);
document.getElementById("pause-ambient").addEventListener("click", pauseAmbient);
document.getElementById("resume-ambient").addEventListener("click", resumeAmbient);
document.getElementById("cancel-ambient").addEventListener("click", cancelAmbient);
document.getElementById("submit-ambient").addEventListener("click", submitAmbient);

// Cleanup function to destroy the SDK and event listeners
// Call this function when you no longer need the SDK
function destroy() {
  isSukiReady = false;
  unsubscribeInit();
  unsubscribeReady();
  sdkClient.destroy();
  
  // Remove event listeners
  document.getElementById("start-ambient").removeEventListener("click", startAmbient);
  document.getElementById("pause-ambient").removeEventListener("click", pauseAmbient);
  document.getElementById("resume-ambient").removeEventListener("click", resumeAmbient);
  document.getElementById("cancel-ambient").removeEventListener("click", cancelAmbient);
  document.getElementById("submit-ambient").removeEventListener("click", submitAmbient);
  
  // Clear the root element
  document.getElementById("suki-root").innerHTML = "";
}

Update encounter context and ambient options programmatically

You can update the visit (encounter) context and ambient options whenever anew encounter loads in your EHR. Providing current context ensures that the Suki Platform generates accurate documentation for the specific visit. The encounter is the patient visit. An ambient session is one recording for that visit.

Update the encounter context

When the patient or visit details change, update the encounter context before you start an ambient session, or after the current ambient session ends.

You cannot change the encounter while an ambient session is in progress. Calling setEncounter() during an active ambient session fails with error SUKI0014.

• JavaScript: Call setEncounter() on the client.
• React: Use the encounter prop on the <SukiAssistant> component.

Update ambient options

You can also update the ambientOptions, such as required note sections or diagnoses, during an active session.

• JavaScript: Call setAmbientOptions() on the client.
• React: Use the ambientOptions prop on the <SukiAssistant> component.

Update the encounter as soon as the EHR context changes, and before you start ambient. You can update ambient options at any time, including during an active ambient session.

JavaScript

// Update encounter data
sdkClient.setEncounter({
  identifier: "qsc2393g-b0b1-499d-a4e9-983cq125g5op",
  patient: {
    identifier: "25eb905-1232-082132-aw12320do4r",
    name: {
      use: "official",
      family: "Smith",
      given: ["Jane"],
      suffix: [],
    },
    birthDate: "1985-05-15",
    gender: "Female",
  },
});

// Update ambient options
sdkClient.setAmbientOptions({
  sections: [
    { loinc: "48765-2" },
    { loinc: "10157-6" },
    { loinc: "10164-2" },
  ],
  diagnoses: {
    values: [
      {
        codes: [
          { code: "I10", description: "Essential hypertension", type: "ICD10" },
        ],
        diagnosisNote: "Hypertension",
      },
    ],
  },
  visitContext: {
    visitType: "ESTABLISHED_PATIENT",
    encounterType: "AMBULATORY",
    reasonForVisit: "Follow-up for hypertension",
    chiefComplaint: "Blood pressure check",
  },
  providerContext: {
    providerRole: "PRIMARY/ATTENDING",
  },
});

Available cookbooks

AmbientWeb SDK

Seed Patient Context for the Web SDK

Seed patient context for Web SDK.

5 min

AmbientAPI

Share One Note Across Products

Share one note with emr_encounter_id.

5 min

Available tutorials

Web SDK

Build a Web SDK Ambient Session

Authenticate, initialize the Web SDK in React, and mount SukiAssistant for an ambient encounter.

15 minIntermediate

Next steps

Track session state: Ambient session status

Configure problem-based notes: PBC

Return to Ambient session overview