Skip to main content
UpdatedFrom v2.2.0+, you can pass optional session-level metadata in ambientOptions (in mount or setAmbientOptions) to improve note generation. When you set 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.
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

​
Controlled session management

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 (). Longer strings can fail during composition or ambient workflows. See Patient and Encounter.
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.

​
Update session encounter and ambient options

You can update the session encounter and ambient options whenever a new encounter loads in your EHR. Providing current context ensures that the Suki Platform generates accurate documentation for the specific visit.

​
Update the encounter

When the patient or visit details change, you must update the encounter context.
  • JavaScript: Call setEncounter() on the client.
  • React: Use the encounter prop on the <SukiAssistant> component.

​
Update ambient options

You can also update the ambient options, 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.
Updating the encounter and ambient options as soon as the EHR context changes ensures that the session is in sync with the latest context.

​
Next steps

Track session state: Ambient session status Configure problem-based notes: PBC Return to Ambient session overview
Last modified on June 4, 2026