> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web SDK Introduction

> A collection of JavaScript & React libraries to build web applications on top of Suki Ambient intelligence capabilities with pre-built UI components

<Callout title="Updates" color="orange" icon="bell">
  **New**

  * From **v3.3.0**, the Headed Web SDK can show **Patient Summary** on the patient profile. Clinicians see a short snippet, then expand it for the full summary. Enable Patient Summary for your organization, keep FHIR data current in CKG, and pass matching **`encounter.identifier`** and **`encounter.practitionerFhirId`** when you initialize and when you mount. Refer to [Patient Summary in Web SDK](/web-sdk/guides/patient-summary).

  * The Web SDK is <Tooltip tip="Interoperability lets different Suki ambient products contribute to the same clinical note for a patient visit. Pass a shared EMR encounter ID so clinicians can start, continue, or re-ambient across Ambient APIs, Mobile SDK, Headless Web SDK, and Web SDK." cta="Learn more" href="/documentation/concepts/ambient-clinical-notes/ambient-interoperability">interoperable</Tooltip> with other Suki products that support ambient workflows. Pass a shared encounter identifier so clinicians can continue the same clinical note across Ambient APIs, Mobile SDK, and Web SDK. Refer to [Ambient interoperability](/web-sdk/guides/ambient-interoperability).
</Callout>

The Suki Web SDK is a JavaScript and React library that provides **pre-built UI components** and **React hooks** to integrate <Tooltip tip="Ambient documentation captures clinical conversations and generates notes automatically." cta="View in Glossary" href="/Glossary/a">ambient</Tooltip> intelligence into your web application.

Use the Web SDK when you want to embed Suki's ambient UI without designing the frontend yourself. Integrate with **Suki.js**, our core **JavaScript/TypeScript SDK**.

After you initialize the SDK, you can add features like:

* Ambient note generation
* Medical transcription
* Note management
* Form filling
* Dictation
* Medication orders
* Patient Summary on the patient profile
* Interoperability with other Suki products
* Write submitted notes to your EHR

## Common integration patterns and use cases

The Web SDK provides a pre-built ambient UI for recording, review, editing, and submission in the browser. Your application owns mount configuration, submission handling, and how notes are written back to your EHR.

The following examples show common ways to integrate the Web SDK into your web application.

<CardGroup cols={2}>
  <Card title="Capture Ambient Notes with Pre-Built UI" icon="file-medical">
    Mount the headed Web SDK in your web app so clinicians can record, review, and edit ambient notes in Suki's UI, then handle note submission in your application.
  </Card>

  <Card title="Edit Notes with Built-In Dictation" icon="microphone">
    Use the Web SDK's built-in Dictation controls while clinicians review an ambient note so they can correct or add text without leaving the editor.
  </Card>

  <Card title="Capture Problem Context" icon="list-check">
    Pass PBC sections and existing diagnoses in **`ambientOptions`** so the note organizes findings around problems and merges EMR diagnoses with the visit discussion.
  </Card>

  <Card title="Capture Medication Orders" icon="pills">
    Enable LOINC **`52471-0`**, let the provider review orders in the SDK UI, then read **`orders`** from the note submission payload and persist them to your EHR after the session completes.
  </Card>

  <Card title="Continue Notes from Another Suki Product" icon="arrows-rotate">
    Open an interoperable ambient note in the Web SDK after capture on another Suki product, such as the Mobile SDK or Ambient APIs, so clinicians can review, edit, and submit on desktop.
  </Card>

  <Card title="Show Patient Summary on the Profile" icon="list-check">
    Pass **`encounter.identifier`** and **`encounter.practitionerFhirId`** when you initialize and when you mount so clinicians can open a pre-visit Patient Summary on the patient profile.
  </Card>

  <Card title="Write Submitted Notes to Your EHR" icon="upload">
    Listen for note submission callbacks, map section content and optional orders into your charting model, and persist the final documentation in your EHR.
  </Card>
</CardGroup>

## Supported platforms

The SDK is supported on the following platforms:

<CardGroup cols={2}>
  <Card title="React" icon="react">
    The SDK is supported on React.

    Install the Suki Web SDK for React:

    <div className="install-btns-v2">
      <button className="install-btn-v2" data-cmd="npm install @suki-sdk/react">
        <span className="install-btn-v2-label">Install for React</span>

        <span className="install-btn-v2-copy">
          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
            <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />

            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
          </svg>
        </span>

        <span className="install-btn-v2-check"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round"><polyline points="20 6 9 17 4 12" /></svg> Command Copied!</span>
      </button>
    </div>
  </Card>

  <Card title="Vanilla JavaScript" icon="js">
    The SDK is supported on Vanilla JavaScript.

    Install the Suki Web SDK for Vanilla JavaScript:

    <div className="install-btns-v2">
      <button className="install-btn-v2" data-cmd="npm install @suki-sdk/js">
        <span className="install-btn-v2-label">Install for JavaScript / TypeScript</span>

        <span className="install-btn-v2-copy">
          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
            <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />

            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
          </svg>
        </span>

        <span className="install-btn-v2-check"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round"><polyline points="20 6 9 17 4 12" /></svg> Command Copied!</span>
      </button>
    </div>
  </Card>
</CardGroup>

<Card title="Other Frameworks" icon="angular">
  The SDK is supported on other frameworks like Vue, Angular, etc.
</Card>

<Info>
  While it is optimized for **React**, you can also easily integrate it with **vanilla JavaScript** or other frameworks.
</Info>

<Note>
  If you are using `@suki-sdk/js` or `@suki-sdk/react`, you can use the `Core` and `Dictation` from the package itself. You do not need to install the `@suki-sdk/core` and `@suki-sdk/dictation` packages separately.
</Note>

## How the Web SDK works

The following diagram illustrates the Web SDK architecture and workflow:

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#111827','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFFFF','tertiaryColor':'#F9FAFB','tertiaryTextColor':'#111827','tertiaryBorderColor':'#D1D5DB'}}}%%
graph TB
    subgraph client["Your web application"]
        direction TB
        A["Application code<br/><small>React / JavaScript / Other Frameworks</small>"]
        B["Suki Web SDK<br/><small>@suki-sdk/js or @suki-sdk/react</small>"]
        C["Pre-built UI<br/><small>Recording • Transcription • Notes</small>"]
        A --> B
        B --> C
    end

    subgraph platform["Suki backend"]
        direction TB
        D["Authentication service<br/>"]
        E["Ambient service<br/>"]
        F["AI engine<br/>"]
    end

    B -->|Authenticate| D
    C -->|Stream audio| E
    E -->|Process| F
    F -->|Return results| C

    style client fill:#FFFADE,stroke:#D1D5DB,stroke-width:2px,color:#111827
    style platform fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style A fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style B fill:#FFE148,stroke:#111827,stroke-width:3px,color:#111827
    style C fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style D fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style E fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style F fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
```

### Architecture workflow

<Steps>
  <Step title="Client Side (Your Web Application)" icon="user">
    * Your React, JavaScript, or web app that integrates the SDK.
    * Core SDK package that handles authentication, session management, and communication.
    * Pre-built UI for recording, transcription, and note display.
  </Step>

  <Step title="Suki Backend" icon="server">
    * Validates partner credentials (Partner ID and token).
    * Manages audio streaming and processing.
    * Processes audio in real-time and generates structured clinical notes.
  </Step>

  <Step title="Data Flow" icon="arrow-right">
    <Callout>
      1. Initialize SDK with partner credentials → Authenticate with Suki's backend.
      2. Mount pre-built UI with encounter data.
      3. User starts recording → SDK streams audio to ambient Service.
      4. AI Engine processes audio and generates notes.
      5. Results return through Suki Backend → UI displays the note and transcript.
    </Callout>
  </Step>
</Steps>

## Web SDK capabilities

<CardGroup cols={2}>
  <Card title="Ambient Note Generation" icon="file-text">
    Capture spoken patient encounters and generate structured clinical notes in real time.

    <Accordion title="Context-Aware Processing">
      Organize medical conversations into the appropriate clinical sections.
    </Accordion>

    <Accordion title="Smart Formatting">
      Use LOINC codes to segment content into sections such as `HPI`, `Assessment`, and `Physical Exam`.
    </Accordion>

    <Accordion title="Background Processing">
      Run ambient capture in the background during consultations without disrupting the provider workflow.
    </Accordion>
  </Card>

  <Card title="Medical Transcription" icon="microphone">
    Transcribe clinical conversations with support for specialty-specific terminology, multiple languages, and accents.

    <Accordion title="Specialty-Specific Terminology">
      Support terminology specific to different medical specialties.
    </Accordion>

    <Accordion title="Multiple Languages and Accents">
      Support multiple languages and accents for medical transcription.
    </Accordion>
  </Card>

  <Card title="Note Management" icon="file-lines">
    Manage clinical notes within your application.

    <Accordion title="Note Editor">
      Edit and format AI-generated clinical content with section-level interaction.
    </Accordion>

    <Accordion title="Note Archive">
      View and manage current and historical notes associated with a patient.
    </Accordion>
  </Card>

  <Card title="Dictation" icon="microphone-lines">
    Use built-in Dictation controls to correct or add text while reviewing an ambient note.

    <Accordion title="In-Editor Dictation">
      Dictate directly into the note editor without leaving the Suki UI.
    </Accordion>

    <Accordion title="JavaScript and React">
      Use Dictation with both `@suki-sdk/js` and `@suki-sdk/react`.
    </Accordion>
  </Card>

  <Card title="Form Filling" icon="file-pen">
    Capture structured medical form data through the Web SDK.

    <Accordion title="Structured Capture">
      Let clinicians complete forms through the headed Web SDK experience instead of a free-text-only workflow.
    </Accordion>

    <Accordion title="Included Clients">
      Import Form filling from `@suki-sdk/js` or `@suki-sdk/react` without installing a separate Form filling package.
    </Accordion>
  </Card>

  <Card title="Medication Orders" icon="pills">
    Generate medication order suggestions during ambient sessions and review them in the built-in Orders section.

    <Accordion title="LOINC Enablement">
      Enable medication orders by including LOINC code `52471-0` in `ambientOptions.sections`.
    </Accordion>

    <Accordion title="EHR Hand Off">
      Read suggested `orders` from the note submission payload and persist them in your EHR after the session completes.
    </Accordion>
  </Card>

  <Card title="Patient Summary" icon="list-check">
    Show a pre-visit Patient Summary on the headed patient profile when your organization is enabled and matching FHIR data is in CKG.

    <Accordion title="Snippet and Full Summary">
      Show a short snippet on the patient profile and expand it to view the full summary.
    </Accordion>

    <Accordion title="Encounter Context">
      Pass `encounter.identifier` and `encounter.practitionerFhirId` when you initialize and when you mount so the profile can show the summary.
    </Accordion>

    <Accordion title="Hosted UI">
      The Web SDK owns the Patient Summary UI. Your application does not build summary screens or call the generate, status, or retrieve APIs for this headed workflow.
    </Accordion>
  </Card>

  <Card title="Problem-Based Charting" icon="notes-medical">
    Organize ambient notes around patient problems.

    <Accordion title="Problem Sections">
      Mark a Problem-Based Note section in `ambientOptions` so findings are grouped by problem.
    </Accordion>

    <Accordion title="Existing Diagnoses">
      Pass existing diagnoses from the EMR so the session can merge them with information discussed during the visit.
    </Accordion>
  </Card>

  <Card title="Ambient Interoperability" icon="share-nodes">
    Continue the same clinical note across Suki products that support ambient workflows for a shared patient encounter.

    <Accordion title="Shared Encounter Identifier">
      Pass a shared encounter identifier so clinicians can start, continue, or re-ambient across Ambient APIs, Mobile SDK, Headless Web SDK, and Web SDK.
    </Accordion>

    <Accordion title="Cross-Product Continuity">
      Capture on one product and review, edit, or submit on another without restarting the note from scratch.
    </Accordion>
  </Card>

  <Card title="Minimized Layout" icon="window-minimize">
    Run ambient capture in a compact, viewport-aligned widget so your application can reclaim screen space.

    <Accordion title="Background Capture">
      Continue capturing audio while the UI remains minimized beside the EHR or patient chart.
    </Accordion>

    <Accordion title="Layout States">
      Listen for layout changes when the UI expands, minimizes, or pauses.
    </Accordion>
  </Card>

  <Card title="Telehealth Audio Capture" icon="video">
    Generate ambient documentation during remote visits by capturing call audio in the browser.

    <Accordion title="Browser Tab Audio">
      Capture audio from a Chrome tab when the telehealth call runs in the browser.
    </Accordion>

    <Accordion title="On-Device System Audio">
      Capture system audio through the browser share dialog, including desktop call apps such as Zoom or Teams when Share system audio is enabled.
    </Accordion>
  </Card>

  <Card title="Multilingual Sessions" icon="language">
    Run ambient sessions with multilingual support for supported languages.

    <Accordion title="Language Selection">
      Configure the session language so transcription and note generation match the visit.
    </Accordion>

    <Accordion title="Clinical Continuity">
      Keep the same headed ambient workflow while supporting multilingual encounters.
    </Accordion>
  </Card>

  <Card title="Visit and Provider Context" icon="clipboard-list">
    Pass optional visit and provider metadata in `ambientOptions` to improve note generation for the session.

    <Accordion title="Visit Context">
      Include visit type, encounter type, reason for visit, and chief complaint when available.
    </Accordion>

    <Accordion title="Provider Context">
      Include the provider role when mounting or calling `setAmbientOptions`.
    </Accordion>
  </Card>

  <Card title="Session Status and Events" icon="clock">
    Track the ambient session lifecycle in real time so your application can respond to session changes.

    <Accordion title="Lifecycle Events">
      Listen for ambient start, pause, resume, cancel, and submit events from the SDK.
    </Accordion>

    <Accordion title="Session Identifiers">
      Read `ambientSessionId` and `activeAmbientId` to follow the active recording and report issues with the correct session context.
    </Accordion>
  </Card>

  <Card title="Session Recovery" icon="arrows-rotate">
    Recover an in-progress ambient session after an unexpected refresh or interruption.

    <Accordion title="Resume Mid-Visit">
      Restore the ambient workflow so clinicians can continue documentation without restarting the visit from scratch.
    </Accordion>

    <Accordion title="Session Continuity">
      Keep encounter and recording context aligned after the browser reloads.
    </Accordion>
  </Card>

  <Card title="Offline Mode" icon="wifi">
    Continue ambient capture when connectivity is limited, then sync when the connection returns.

    <Accordion title="Limited Connectivity">
      Keep recording usable during temporary network loss or unstable connections.
    </Accordion>

    <Accordion title="Sync When Online">
      Upload captured audio and continue the ambient workflow after connectivity is restored.
    </Accordion>
  </Card>

  <Card title="Branding and Layout" icon="paint-brush">
    Customize the headed Web SDK appearance to fit your application shell.

    <Accordion title="Recommended Dimensions">
      Use the default recommended size of 360 pixels wide and 912 pixels tall, or adjust the height to match the enclosing window.
    </Accordion>

    <Accordion title="Theme Colors">
      Apply optional theme colors to align the SDK UI with your product branding.
    </Accordion>
  </Card>

  <Card title="UI Visibility Controls" icon="eye">
    Show or hide SDK chrome to match your application workflow.

    <Accordion title="Close Controls">
      Use the embedded close button or control visibility programmatically from your application.
    </Accordion>

    <Accordion title="UI Options">
      Configure UI options at mount time to control which elements appear in the headed experience.
    </Accordion>
  </Card>

  <Card title="Note Submission and EHR Writeback" icon="upload">
    Handle completed notes in your application and persist documentation in your EHR.

    <Accordion title="Submission Callbacks">
      Listen for note submission success so your application receives the final note content.
    </Accordion>

    <Accordion title="Chart Persistence">
      Map section content and optional orders into your charting model, then write the final documentation to your EHR.
    </Accordion>
  </Card>

  <Card title="Token Refresh" icon="key">
    Keep Web SDK sessions authenticated without requiring clinicians to sign in again mid-day.

    <Accordion title="Automatic Suki Token Refresh">
      The SDK monitors expiration and refreshes the Suki access token in the background while your `partnerToken` remains valid.
    </Accordion>

    <Accordion title="Partner Token Rotation">
      When your EHR issues a new partner token, call `setPartnerToken` at runtime without a full re-authentication flow.
    </Accordion>
  </Card>

  <Card title="Dynamic Encounter Switching" icon="user-doctor">
    Update the active encounter when clinicians move between appointments in your EHR.

    <Accordion title="Set Encounter">
      Call `setEncounter` in JavaScript, or update the React `encounter` prop, when the clinician opens another visit.
    </Accordion>

    <Accordion title="New Patient Summary">
      Switching the encounter loads the Patient Summary for the new encounter on the patient profile.
    </Accordion>
  </Card>
</CardGroup>

## Key benefits

The web SDK provides the following benefits:

<AccordionGroup>
  <Accordion icon="clock" title="Fast Integration">
    Quickly add Suki's features using our built-in UI.
  </Accordion>

  <Accordion icon="fast-forward" title="Optimized Performance">
    Built for accuracy and speed in a web environment.
  </Accordion>

  <Accordion icon="user" title="Focus on Your Application">
    Let our components handle the Suki UI so your team can focus on your product.
  </Accordion>
</AccordionGroup>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to our [Installation guide](/web-sdk/installation) to get started with the Suki SDK.