Platform Client & Provider

Headless Web SDK Client and Provider reference

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

import { PlatformClient } from '@suki-sdk/platform-react';

function App() {
  return <PlatformClientProvider client={platformClient}>
<YourApp />
</PlatformClientProvider>;
}

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

const client = new PlatformClient({
  env: "staging",
  enableDebug: true,
  logLevel: "error"
});

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.

env · string

The Suki environment the client targets. Examples in this documentation use "staging".

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

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

Import

import { PlatformClientProvider } from '@suki-sdk/platform-react';

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.

const { ambientSessionId, noteId } = await client.createNewAmbientSession({
  encounterId: "your-encounter-id",
  emrEncounterId: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
});

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

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

multilingual · 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

await client.startAmbientSession(ambientSessionId, {
  audio: { deviceId: selectedMicrophoneId }, // New in v0.3.1
});

ambientSessionId · string · required

The ambient session identifier returned from create.

options.audio.deviceId · string

Optional: MediaDeviceInfo.deviceId for an audioinput device. When set, capture uses getUserMedia with that exact device. Your app owns device enumeration 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

await client.pauseAmbientSession(ambientSessionId);

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

await client.resumeAmbientSession(ambientSessionId, { // New in v0.3.1
  audio: { deviceId: nextMicrophoneId },
});

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

await client.pauseAmbientSession(ambientSessionId);
await client.resumeAmbientSession(ambientSessionId, { // New in v0.3.1
  audio: { deviceId: nextMicrophoneId },
});

ambientSessionId · string · required

The ambient session identifier for the recording to resume.

options.audio.deviceId · string

Optional: MediaDeviceInfo.deviceId for an audioinput device. Applied when capture starts again after resume.

Which microphone start and resume use

What you pass	Microphone the SDK uses
No options argument on resumeAmbientSession	The last microphone that started or resumed successfully for this session, while the session is still in memory
{ audio: { deviceId } } on start or resume	That deviceId for this attempt
{ audio: undefined }	The browser default microphone. This also clears the stored choice
Start or resume fails	The last successful microphone stays stored. The failed deviceId does not replace it

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

// Omit audio options: browser default, or reuse last successful selection on resume
await client.startAmbientSession(ambientSessionId);

// Explicitly clear a previous in-memory selection
await client.resumeAmbientSession(ambientSessionId, { // New in v0.3.1
  audio: undefined,
});

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.

const { notes } = await client.getEncounterInfo(
  "6ec3920f-b0b1-499d-a4e9-889bf788e5ab"
);

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

await client.endRemoteAmbientSession({
  ambientSessionId: blockingSessionId,
});

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.

await client.cancelRemoteAmbientSession({
  ambientSessionId: blockingSessionId,
});

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.

setSessionContext

Use setSessionContext to attach patient, provider, visit, section, and diagnosis data to an ambient session. That includes existing section text and Embedded Form templates on sections[].precharted_content.

Call setSessionContext after you create the session and before you submit. You can call it before recording starts.

setSessionContext sends the complete context to Suki. It checks that the session is still created, and the Headless Web SDK stores that full context in IndexedDB so it can upload with the session if the device goes offline. Call setSessionContext before updateSessionContext when you need that offline path.

Embedded Forms on sections[].precharted_content require Headless Web SDK v0.3.1 or later.

await client.setSessionContext({
  ambientSessionId,
  sections: [
    {
      loinc: "10164-2",
      precharted_content: [ // New in v0.3.1
        { type: "string", text: "Patient reports intermittent chest pain for 2 weeks." },
      ],
    },
  ],
});

On failure, throws AmbientSessionError with code: "ContextUpdateFailed" when the session is no longer in the created state (for example after submit or cancel), or when the request fails. setSessionContext from useAmbientSession throws that failure as a string. For field shapes, refer to SessionContext. For seed, update, and read examples, refer to Seed and read Embedded Forms.

updateSessionContext

Use updateSessionContext when you need to change session context after the first setSessionContext call, for example to change Embedded Form templates during the visit. You must pass updateMask so the SDK knows which top-level fields to replace.

For Embedded Forms, put sections in updateMask (prefer ["sections"]; the string "sections" also works), then send the full sections list you want. That list replaces the previous sections list and does not append it. Do not use nested paths under sections, such as sections.precharted_content or sections.loinc. Nested paths on object fields, such as patient.dob, are supported when you are updating that field.

await client.updateSessionContext({
  ambientSessionId,
  updateMask: ["sections"],
  sections: [
    {
      loinc: "10164-2",
      precharted_content: [ // New in v0.3.1
        {
          type: "structured",
          template_id: "partner-hpi-iv-1",
          fields: [{ key: "onset", type: "text", context: "When did symptoms start?" }],
        },
      ],
    },
  ],
});

On failure, throws PlatformError with reason: "updateSessionContextFailed" when ambientSessionId or updateMask is missing, or when the request fails. In React, prefer useUpdateAmbientSessionContext, which wraps the same call.

Structured data and content getters

After note generation completes, use these methods to read results. Filled Embedded Forms come back in section_structured_values. The SDK does not poll for them in the background, so call or refetch when your app knows the note is ready. Use the section helpers when you only need Embedded Forms. Use the full structured data helpers when you also need diagnoses and orders. Note structured data returns diagnoses and orders only in this release. It does not include Embedded Forms, so read Embedded Forms from the session or encounter helpers instead.

The optional cumulative flag applies only to getAmbientSessionContent. It does not apply when you read section structured data.

Method	Returns
getAmbientSessionStructuredData(ambientSessionId)	{ structured_data: { diagnoses, orders, section_structured_values } } for the session
getAmbientSessionSectionStructuredData(ambientSessionId)	{ section_structured_values } for the session
getAmbientSessionContent({ ambientSessionId, cumulative? })	Note text for the session (cumulative is optional and applies here only)
getAmbientEncounterStructuredData(encounterId)	{ structured_data: { diagnoses, orders, section_structured_values } } for the encounter
getAmbientEncounterSectionStructuredData(encounterId)	{ section_structured_values } for the encounter
getAmbientEncounterContent(encounterId)	Note text for the encounter
getAmbientNoteStructuredData(noteId)	Diagnoses and orders for the note (no Embedded Forms in this release)
getAmbientNoteContent(noteId)	Note text for the note

In React, prefer hooks such as useAmbientSessionSectionStructuredData and useAmbientSessionStructuredData. For the full hook list and examples, refer to Seed and read Embedded Forms.

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.