Skip to main content
The Suki Headless Web SDK provides PlatformClient and PlatformClientProvider to help you integrate Suki Headless Web SDK functionality into your application. PlatformClient The PlatformClient acts as the shared runtime object for the SDK within your app. You should create a single instance of this object and reuse it throughout your application to ensure consistency. PlatformClientProvider The PlatformClientProvider is a React wrapper that makes your PlatformClient instance available to all child components. This allows you to use Suki hooks, such as useAuth, useAmbient, and useAmbientSession, to build your integration quickly.

​
PlatformClient

​
Import

Before you can use the PlatformClient, you need to import it into your application.
React

​
Creating an instance

Create the client once for your app (for example at module scope or outside your root component) so it is not recreated on every render.
React
The object you pass to new PlatformClient({ ... }) sets how that client behaves for your app.

​
Configuration

These are the settings you pass when you call new PlatformClient({ ... }) in your application.
​
string
The Suki environment the client targets. Examples in this documentation use "staging".
​
boolean
When true, the client runs in a debug-oriented mode so you can troubleshoot during development. Use false when you do not want that behavior in production.
​
string
The logging level for the client. Examples in this documentation use "error".

​
PlatformClientProvider

Before you can use the PlatformClientProvider, you need to import it into your application.

​
Wrap your app

Create a single PlatformClient instance and wrap your application with PlatformClientProvider. Hooks such as useAuth, useAmbient, and useAmbientSession must run under this provider.
To use Headless Web SDK, you must wrap your app with PlatformClientProvider above any component that calls Headless Web SDK hooks. Those hooks read the shared PlatformClient from React context that the provider supplies.Refer to the Quickstart for a full component tree and useAuth example.

​
Ambient session methods on PlatformClient

The React hooks wrap these PlatformClient methods. Use the hooks in most React apps. Call the client directly when you are not using React, or when you want to see the underlying API the hooks delegate to.

​
createNewAmbientSession

Creates an ambient session on Suki’s servers and returns the ids you need for recording and note retrieval. Every create call requires encounterId. That value groups re-ambient sessions on the same clinical note. Reuse the same encounterId whenever you start a new ambient session for that note. Pass emrEncounterId when the note must be shared across Suki products (Web SDK, Mobile SDK, Headless Web SDK, Ambient API). Without it, the session works in your app only and is not interoperable.
​
string
required
Your encounter identifier for this note. Maps to Ambient API encounter_id. Reuse the same value for every re-ambient session on that note.
​
string
Optional: EMR or EHR encounter identifier. Maps to Ambient API emr_encounter_id. Accepts a UUID or non-UUID value, at most 36 characters. Required for interoperability across Suki products.
​
boolean
Optional: Enables multilingual ambient capture when your partner configuration supports it.
On success, returns { ambientSessionId, noteId }. Use ambientSessionId with startAmbientSession or useAmbientSession. Store noteId when you call Ambient API note endpoints. If another Suki product already holds the active session for the same EMR encounter, create throws PlatformError with reason: "sessionAlreadyExists". Read blockingSessionId from error.additionalProperties, then call cancelRemoteAmbientSession or endRemoteAmbientSession before you retry create. Refer to Handle ambient session conflicts.

​
startAmbientSession

Start recording for an ambient session you already created. Pass the ambientSessionId from createNewAmbientSession or useAmbient. You can also pass a microphone deviceId to use a specific microphone. If you leave deviceId out, the browser default microphone is used. Example: Pass a microphone deviceId to use a specific microphone
​
string
required
The ambient session identifier returned from create.
​
string
Optional: MediaDeviceInfo.deviceId for an audioinput device. When set, capture uses getUserMedia with that exact device. Your app owns and selection UI.
  • When recording starts, the promise resolves.
  • If the microphone cannot start, including when the deviceId you passed is missing or disconnected, the error code is StartSessionFailed and the reason is AudioRecorderFailure. The cause is the browser microphone error. The Headless Web SDK does not use the browser default microphone instead. Refer to Starting a session.
  • In React, call useAmbientSession and pass config.audio.deviceId. start() often throws a string instead of an object with code and reason. Refer to Select a microphone guide for more details.

​
pauseAmbientSession

Pauses an active ambient recording. Recording stops until you call resumeAmbientSession. Example: Pause a recording
​
string
required
The ambient session identifier for the recording to pause.
On success, returns Promise that resolves when the session is paused.

​
resumeAmbientSession

Resumes a paused ambient recording. Pass the same optional microphone options shape as startAmbientSession.
To switch microphones mid-visit, pause first, then resume with the new deviceId. There is no public switchMicrophone API, and changing the device while recording is active does not switch the microphone that is already in use. Example: Switch microphones mid-visit
​
string
required
The ambient session identifier for the recording to resume.
​
string
Optional: MediaDeviceInfo.deviceId for an audioinput device. Applied when capture starts again after resume.

​
Which microphone start and resume use

The Headless Web SDK keeps the microphone choice in memory only. It does not save it to IndexedDB. After a page reload, an SDK remount, or session recovery, pass deviceId again from your app. Leaving out the options argument does not bring the previous microphone back. Example: Omit audio options to use the browser default, or explicitly clear a previous in-memory selection
On resume mic capture failure (including an unavailable exact deviceId), the error uses code: "ResumeSessionFailed" and reason: "AudioRecorderFailure". Refer to Resuming a session.

​
getEncounterInfo

Looks up shared notes and ambient session identifiers for one EMR encounter. Use this when you need noteId and session ids before you call Ambient API note-level endpoints. The method does not return note content, transcripts, or recordings.
​
string
required
Partner EMR or application encounter identifier. Must be non-empty. This is the method’s only argument.
Returns { notes }. notes is always an array, including when no notes exist. Each note includes note_id, status, timestamps, and a sessions array with optional artifact names (for example "content", "transcript", "recording"). On failure, throws PlatformError with reason: "getEncounterInfoFailed". In React, prefer useGetEncounterInfo({ emrEncounterId }).

​
endRemoteAmbientSession

Ends an ambient session that is running in another Suki product and blocking create in your app. Use this after sessionAlreadyExists when you want the remote session to finish and process any audio already captured. Pass the blocking session id from the conflict error, not your local session id unless they are the same.
On success, returns Promise<void>. Retry createNewAmbientSession with the same encounterId and emrEncounterId. On failure, throws PlatformError with reason: "endRemoteSessionFailed".

​
cancelRemoteAmbientSession

Discards an ambient session that is running in another Suki product and blocking create in your app. Use this after sessionAlreadyExists when you want to drop the remote session without generating a note from its audio. Pass the blocking session id from the conflict error, not your local session id unless they are the same.
On success, returns Promise<void>. Retry createNewAmbientSession with the same encounterId and emrEncounterId. On failure, throws PlatformError with reason: "cancelRemoteSessionFailed". For end-to-end interoperability workflows, refer to Ambient interoperability, Handle ambient session conflicts, and Read shared ambient notes.

​
Next steps

Quickstart - Install, provider, useAuth, and ambient flow. Manage ambient session - Select a microphone with useAmbientSession. Ambient interoperability - Share one clinical note across Ambient products. Handle ambient session conflicts - Clear a blocking remote session, then retry create. Read shared ambient notes - List notes and seed patient context for Web SDK handoff.
Last modified on September 29, 2026