Skip to main content

​
Overview

The Suki Headless Web SDK provides React hooks and core functionality that allow you to integrate ambient intelligence capabilities into your web application while maintaining complete control over your user interface. Unlike the Suki Web SDK, which includes pre-built UI components, the Headless Web SDK gives you the backend functionality and lets you design every aspect of the user experience. This approach gives you maximum flexibility to match your application’s design system and user experience requirements.

​
Key Features

The Headless Web SDK provides all the core capabilities of the Suki platform:

Ambient note generation

Capture clinical conversations and generate structured notes automatically

Real-time audio streaming

Receive real-time audio from the patient-provider conversation

Session management

Full control over recording lifecycle (start, pause, resume, submit)

Custom UI integration

Design your own recording interface, waveforms, and status indicators

React hooks

Simple, declarative API using React hooks for state management

​
When to Use Headless Web SDK

Choose the Headless Web SDK when:
  • You want to embed ambient intelligence into your existing web application with a custom UI
  • You need complete control over the user interface and user experience
  • You want to match your application’s existing design system and branding
  • You need to optimize performance by controlling what UI components are rendered
  • You’re building a custom workflow that requires specific UI interactions
If you prefer pre-built UI components and want to get started quickly, consider using the Suki Web SDK instead.

​
How It Works

The following diagram illustrates the Headless Web SDK architecture and workflow:

​
Architecture Workflow

Client Side (Your Web Application)

  • Your React application that integrates the Headless Web SDK
  • React SDK package (@suki-sdk/platform-react) that provides React hooks for authentication, session management, and recording control
  • Your custom UI components built using the hook state and methods for recording controls, status display, and visualization

Suki Backend

  • Authentication Service: Validates user credentials and manages session tokens
  • Ambient Service: Handles audio streaming, session management, and real-time transcription
  • AI Engine: Processes audio data and generates structured clinical notes

Data Flow

  1. Initialize hooks with partner credentials -> Authenticate with Suki backend
  2. Create ambient session using useAmbient hook -> Get ambientSessionId
  3. Initialize useAmbientSession hook with the ambientSessionId -> Get recording controls
  4. Build custom UI using hook state and methods
  5. User starts recording using start() method -> SDK streams audio to Ambient Service
  6. AI Engine processes audio and generates notes
  7. Results return through hooks -> Your custom UI displays the note and transcript

​
Supported Platforms

The Headless Web SDK is currently supported on:

React

The SDK provides React hooks optimized for React applications. Requires React 18.0 or higher.

​
Next Steps

Get started by following these steps:

Install the SDK

Follow the Installation guide to add the package to your project

Set up authentication

Learn how to authenticate users in the Authentication Hook guide

Create your first session

See how to create an ambient session in the Create Ambient Session guide

Build your UI

Learn to manage recording in the Manage Ambient Session guide