> ## 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.

# Headless Web SDK Quickstart

> Get started with the Suki Headless Web SDK, from installation to your first recording

This guide walks you through setting up the Suki Headless Web SDK in your React application, from installation to creating your first ambient recording session.

**What you will do**

1. **Install** `@suki-sdk/platform-react` in your React project.
2. **Wrap** your app with **`PlatformClient`** and **`PlatformClientProvider`** at the root so all SDK hooks share one client.
3. **Authenticate** with **`useAuth`** inside that tree so users are signed in and tokens are available.
4. **Create** an ambient session with `useAmbient`, then **control recording** with `useAmbientSession` (start, pause, resume, submit, and optional context).
5. **Wire up** a minimal end-to-end flow using the complete example as a reference.

<Tip>
  **Using an AI coding tool?**

  Copy the following prompt to add the Suki developer documentation as a skill and [MCP server](/documentation/mcp) to your tool for better AI-assisted coding during the integration process. For all AI options (contextual menu, `llms.txt`, and `skill.md`), refer to [AI-optimized documentation](/documentation/ai-optimized-documentation).

  <Prompt description="Install the Suki developer docs as a skill to get context on Suki's developer tools, APIs, and SDKs. Add the [MCP server](/documentation/mcp) for documentation search." icon="gear" iconType="regular" actions={["copy", "cursor"]}>
    Install the Suki developer docs as skill to get context on Suki's developer tools, APIs, and SDKs.

    npx skills add [https://developer.suki.ai](https://developer.suki.ai)

    Then add the Suki developer docs MCP server for access to documentation search. Follow the MCP instructions at [https://developer.suki.ai/documentation/mcp](https://developer.suki.ai/documentation/mcp).
  </Prompt>
</Tip>

## Prerequisites

For the rest of this documentation, we assume the following setup is complete:

* You have received your `partnerId` from Suki.
* Your host URLs are on the Suki allowlist.
* Your partner configuration in the Suki Platform points to your correct JWKS endpoint.
* Your JWT token contains the key that you specified as your **User identifier field**.

Refer to the [Prerequisites](/headless-web-sdk/prerequisites) guide for more information.

## Install the package

To begin, install the Suki Headless Web SDK package in your React project:

<CodeGroup title="Install the @suki-sdk/platform-react package">
  ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  pnpm add @suki-sdk/platform-react
  ```

  ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  npm install @suki-sdk/platform-react
  ```

  ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  yarn add @suki-sdk/platform-react
  ```
</CodeGroup>

For detailed setup instructions, refer to the [Installation guide](/headless-web-sdk/installation).

## Required configuration

Create a single **`PlatformClient`** instance and wrap your entire application with **`PlatformClientProvider`**. Hooks such as `useAuth`, `useAmbient`, and `useAmbientSession` must run under this provider.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { PlatformClient, PlatformClientProvider } from '@suki-sdk/platform-react';

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

function App() {
  return (
    <PlatformClientProvider>
      <YourApp />
    </PlatformClientProvider>
  );
}
```

## Authenticate with useAuth

After the provider wraps your app, use **`useAuth`** in a child component (for example **`YourApp`**). This hook manages user identity and provides access tokens needed for all SDK operations.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useAuth } from '@suki-sdk/platform-react';

function YourApp() {
  const {
    isLoggedIn,
    isPending,
    error,
    login
  } = useAuth({
    partnerId: 'your-partner-id', // Required: Replace with your actual partner ID
    partnerToken: 'your-partner-token', // Required: Replace with your actual partner token
    autoRegister: true, // Optional: Automatically register users if they don't exist
    loginOnMount: true, // Optional: Sign in automatically when component mounts
    providerName: 'Dr. John Doe', // Required for auto-registration
    providerOrgId: 'org-123', // Required for auto-registration
    providerSpecialty: 'Cardiology' // Required for auto-registration
  });

  if (isPending) {
    return <div>Signing in...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  if (!isLoggedIn) {
    return <button onClick={login}>Sign In</button>;
  }

  return <div>Ready to use Suki Headless Web SDK</div>;
}
```

<Note>
  If you set `autoRegister: true`, you must provide `providerName`, `providerOrgId`, and `providerSpecialty`. If you prefer manual registration, set `autoRegister: false` and use the `registerUser` method. See the [Authentication hook guide](/headless-web-sdk/guides/hooks/auth-hook) for more details.
</Note>

## Create ambient session

Once authenticated, create an ambient session using the `useAmbient` hook. This creates a session container that you'll use for recording.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useEffect } from 'react';
import { useAmbient } from '@suki-sdk/platform-react';

function SessionCreator({ onSessionReady }) {
  const {
    ambientSessionId,
    session: { create, isPending, isSuccess, error }
  } = useAmbient();

  // Create session when component mounts
  useEffect(() => {
    create();
  }, [create]);

  // Pass session ID to parent when ready
  useEffect(() => {
    if (isSuccess && ambientSessionId) {
      onSessionReady(ambientSessionId);
    }
  }, [isSuccess, ambientSessionId, onSessionReady]);

  if (isPending) {
    return <div>Creating session...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return null;
}
```

<Note>
  You must wait for `isSuccess` to be `true` before attempting to use the `ambientSessionId`. Passing an undefined ID to the recording hooks will cause errors.
</Note>

## Manage recording

Use the `useAmbientSession` hook to control recording. This hook provides methods to start, pause, resume, and submit recordings, along with session status.

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useAmbientSession } from '@suki-sdk/platform-react';

function Recorder({ sessionId }) {
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType, // [!code ++] New in v0.2.2
    setSessionContext
  } = useAmbientSession({
    ambientSessionId: sessionId,
    onAudioChunkAvailable: (chunk) => {
      // Optional: Use audio chunks for visualization
      console.log('Audio chunk received:', chunk);
    }
  });

  // Set session context after starting
  const handleStart = async () => {
    await start();
    // Provide context to improve note generation
    await setSessionContext({
      patient: {
        dob: '1980-01-15',
        sex: 'M'
      },
      provider: {
        specialty: 'Cardiology',
        role: 'Attending Physician'
      },
      visit: {
        visit_type: 'Follow-up',
        encounter_type: 'Office Visit',
        reason_for_visit: 'Chest pain evaluation',
        chief_complaint: 'Chest pain'
      }
    });
  };

  return (
    <div>
      <h3>Status: {sessionStatus}</h3>
      {sessionType === 'offline' && ( // [!code ++:2] added in v0.2.2
        <p>Session will sync when online</p>
      )}
      
      {sessionStatus === 'created' && (
        <button onClick={handleStart}>Start Recording</button>
      )}
      
      {sessionStatus === 'recording' && (
        <>
          <button onClick={pause}>Pause</button>
          <button onClick={submit}>Finish & Submit</button>
        </>
      )}
      
      {sessionStatus === 'paused' && (
        <>
          <button onClick={resume}>Resume</button>
          <button onClick={submit}>Finish & Submit</button>
        </>
      )}
    </div>
  );
}
```

<Tip>
  Always use `setSessionContext` to provide relevant patient or encounter details. This context acts as a hint for the AI, resulting in significantly higher quality clinical notes.
</Tip>

## Complete example

Here's a complete example that brings everything together:

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useState, useEffect } from 'react';
import {
  PlatformClient,
  PlatformClientProvider,
  useAuth,
  useAmbient,
  useAmbientSession
} from '@suki-sdk/platform-react';

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

function App() {
  return (
    <PlatformClientProvider>
      <SukiRecorder />
    </PlatformClientProvider>
  );
}

function SukiRecorder() {
  const [sessionId, setSessionId] = useState(null);

  // Step 1: Authenticate (under PlatformClientProvider)
  const { isLoggedIn, isPending: authPending } = useAuth({
    partnerId: 'your-partner-id', // Required: Replace with your actual partner ID
    partnerToken: 'your-partner-token', // Required: Replace with your actual partner token
    autoRegister: true, // Optional: Automatically register users if they don't exist
    loginOnMount: true, // Optional: Sign in automatically when component mounts
    providerName: 'Dr. John Doe', // Required for auto-registration
    providerOrgId: 'org-123', // Required for auto-registration
    providerSpecialty: 'Cardiology' // Required for auto-registration
  });

  // Step 2: Create session
  const {
    ambientSessionId,
    session: { create, isSuccess: sessionCreated }
  } = useAmbient();

  useEffect(() => {
    if (isLoggedIn && !sessionCreated) {
      create();
    }
  }, [isLoggedIn, sessionCreated, create]);

  useEffect(() => {
    if (ambientSessionId) {
      setSessionId(ambientSessionId);
    }
  }, [ambientSessionId]);

  // Step 3: Manage recording
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType, // [!code ++] New in v0.2.2
  } = useAmbientSession({
    ambientSessionId: sessionId
  });

  if (authPending) {
    return <div>Authenticating...</div>;
  }

  if (!isLoggedIn) {
    return <div>Please sign in</div>;
  }

  if (!sessionId) {
    return <div>Creating session...</div>;
  }

  return (
    <div>
      <h2>Recording Status: {sessionStatus}</h2>
      {sessionType === 'offline' && ( // [!code ++:2] added in v0.2.2
        <p>Session will sync when online</p>
      )}
      
      {sessionStatus === 'created' && (
        <button onClick={start}>Start Recording</button>
      )}
      
      {sessionStatus === 'recording' && (
        <>
          <button onClick={pause}>Pause</button>
          <button onClick={submit}>Submit</button>
        </>
      )}
      
      {sessionStatus === 'paused' && (
        <>
          <button onClick={resume}>Resume</button>
          <button onClick={submit}>Submit</button>
        </>
      )}
    </div>
  );
}
```

## Next steps

Refer to the following guides to learn more:

<Icon icon="file-lines" iconType="solid" /> [Platform client and provider](/headless-web-sdk/api-reference/platform-client) - Understand how to use `PlatformClient` and `PlatformClientProvider`

<Icon icon="file-lines" iconType="solid" /> [Authentication hook](/headless-web-sdk/guides/hooks/auth-hook) - Learn more about authentication options and token management

<Icon icon="file-lines" iconType="solid" /> [Create ambient session](/headless-web-sdk/guides/hooks/ambient-hook) - Understand session creation in detail

<Icon icon="file-lines" iconType="solid" /> [Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook) - Explore all recording controls and session context

<Icon icon="file-lines" iconType="solid" /> [Error handling](/headless-web-sdk/guides/error-handling) - Learn how to handle errors gracefully

<Icon icon="file-lines" iconType="solid" /> [Offline mode](/headless-web-sdk/guides/offline-mode) - Understand how the SDK handles network interruptions