Create Ambient Session

Create an ambient session with useAmbient, pass an encounterId, and obtain an ambientSessionId for recording in the Headless Web SDK

Quick summary

The useAmbient hook creates a new ambient session on Suki’s servers. Call session.create({ encounterId }) with your encounter id. You get back an ambientSessionId for recording.

Use the status flags (isPending, isSuccess, isError) to track creation. When isSuccess is true, pass ambientSessionId to useAmbientSession to start recording.

Last updated:August 2026

Ambient session created with Headless Web SDK is not interoperable yet. We will publish the package in the next release.

The useAmbient hook creates an ambient session on Suki’s servers. It returns ambientSessionId, session.create, and status flags. Pass a required encounterId when you call create. Wait for success before you hand the id to useAmbientSession.

Configuration

Run the hook under PlatformClientProvider with a shared PlatformClient instance.

Common use cases

1. Provision an Ambient Session

   Create an ambient session when a visit begins or when your app is ready. Call session.create({ encounterId: "your-encounter-id" }). encounterId is required. Optional fields include emrEncounterId and multilingual. While the request runs, use:

   • session.isPending to detect an active request.
   • session.isSuccess to confirm that the session was created successfully.
   • session.isError to detect request failures.
2. Pass the Ambient Session to Downstream Workflows

   After the session is created successfully, read the returned ambientSessionId and pass it to useAmbientSession to continue the workflow.

   Only access ambientSessionId after session.isSuccess is true. Do not pass an undefined or incomplete session ID. For more information, refer to the warning in Code example below.

3. Handle Session Creation Errors

   If session creation fails, session.isError is set to true. Read session.error to inspect the failure and implement retry or user-facing error handling logic.

   For implementation details, refer to Error handling.

useAmbient hook

Usage

Call useAmbient() with no arguments from a component under PlatformClientProvider. Destructure ambientSessionId, session.create, and the session status fields.

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

Returns

The hook returns ambientSessionId and a session object with create, status flags, and error. See What it returns.

How session creation works

1. Call the hook: Call useAmbient() in a component under PlatformClientProvider.
2. Create the session: Call session.create({ encounterId }). Always pass your encounter id.
3. Get the session ID: When session.isSuccess is true, use ambientSessionId with useAmbientSession.

The hook provides status flags (isPending, isSuccess, isError) so you can track the creation progress and update your UI accordingly.

What it returns

The hook returns the session identifier and status information about the creation request.

Session identifier

ambientSessionId · string

The unique identifier for your ambient session. This value is undefined until the session is successfully created. Once isSuccess is true, you’ll have a valid session ID to use with other hooks like useAmbientSession.

Status flags

Use these boolean flags to control your UI and handle the creation lifecycle:

session.isPending · boolean

Check this flag to show a loading state in your UI. When true, display a loading spinner, disable buttons, or show a “Creating session.” message. The hook sets this to true while creating the session.

session.isSuccess · boolean

Check this flag to proceed with recording. When true, the session is ready and ambientSessionId contains a valid session ID. Show your recording controls or pass the session ID to the next step in your workflow.

session.isError · boolean

Check this flag to display error messages in your UI. When true, show an error message to the user using details from session.error. You might want to offer a retry option or redirect to an error page.

session.error · SukiError

Use this to display specific error information to users. When session.isError is true, read this object to show error messages, error codes, or troubleshooting information in your UI. It remains null or undefined when there’s no error.

Actions

session.create · (params: { encounterId: string; emrEncounterId?: string; multilingual?: boolean }) => Promise<{ ambientSessionId: string; compositionId: string }>

Creates a new ambient session. encounterId is required. Optional: emrEncounterId, multilingual. Status flags update while the request runs. Call this after sign-in, for example on mount or when the user starts a visit.

Code example

This example shows how to create a session when a user starts a patient visit. The session is created automatically when the component mounts, and the session ID is passed to the parent component once ready.

React

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

export const VisitStarter = ({ onSessionReady }) => {
  const {
    ambientSessionId,
    session: { create, isPending, isSuccess, error }
  } = useAmbient();

  // Create the session when component mounts
  useEffect(() => {
    create({ encounterId: 'your-encounter-id' });
  }, [create]);

  // Pass the session ID to parent once creation succeeds
  useEffect(() => {
    if (isSuccess && ambientSessionId) {
      onSessionReady(ambientSessionId);
    }
  }, [isSuccess, ambientSessionId, onSessionReady]);

  // Show loading state while creating
  if (isPending) {
    return <div>Initializing Suki Session...</div>;
  }

  // Show error if creation failed
  if (error) {
    return <div>Error creating session: {error.message}</div>;
  }

  return null; 
};

What this example does:

1. Initializes the hook - Gets the useAmbient hook and its return values.
2. Creates session on mount - Automatically calls create({ encounterId }) when the component loads.
3. Handles loading state - Shows a loading message while isPending is true.
4. Handles success - Passes the ambientSessionId to the parent component once ready.
5. Handles errors - Displays error messages if creation fails.

Important: Always wait for isSuccess to be true before using ambientSessionId. Passing an undefined session ID to useAmbientSession or other hooks will cause errors.

Trigger session creation manually (e.g., on button click) instead of automatically on mount by calling create({ encounterId }) when the user performs an action.

Available tutorials

Headless Web SDK

Build a Headless Ambient Recorder

Use Headless hooks to sign in, create an ambient session, and control recording in a custom React UI.

20 minIntermediate

Next steps

Once you have created an ambient session, refer to the Manage ambient session guide to start recording audio and manage the ambient session.