Create Ambient Session

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 and a noteId for the shared clinical note.

Pass optional emrEncounterId to make the note interoperable across Ambient products. Use the status flags (isPending, isSuccess, isError) to track creation. When isSuccess is true, pass ambientSessionId to useAmbientSession to start recording.

Last updated:September 2026

To share the clinical note across Ambient APIs, Mobile SDK, Web SDK, and Headless Web SDK, pass emrEncounterId on create. For the full workflow, refer to Ambient interoperability.

The useAmbient hook creates an ambient session on Suki’s servers. It returns ambientSessionId, noteId, session.create, cancelRemote, endRemote, 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

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 (required for interoperability) 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.

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. Store noteId when you need note-level Ambient APIs.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.

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.When another product already holds the active session for the same EMR encounter, the error reason is sessionAlreadyExists. Use cancelRemote or endRemote, then retry create. Refer to Handle ambient session conflicts and Error handling.

useAmbient hook

Usage

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

const {
  ambientSessionId,
  noteId, // New in v0.3.0
  cancelRemote,
  endRemote,
  session: {
    create,
    error,
    isError,
    isPending,
    isSuccess,
  },
} = useAmbient();

Returns

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

How session creation works

Call the hook: Call useAmbient() in a component under PlatformClientProvider.
Create the session: Call session.create({ encounterId, emrEncounterId? }). Always pass your encounter id. Pass emrEncounterId for interoperability.
Get the session and note IDs: When session.isSuccess is true, use ambientSessionId with useAmbientSession, and store noteId for note-level Ambient APIs.

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

string | null

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

string | null

The shared clinical note identifier returned on successful create. Maps to Ambient API note_id. Store this value for note-level Ambient APIs. This value is null until create succeeds.

Status flags

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

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.

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.

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.

Error | null

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 when there’s no error. For remote session conflicts, check reason === "sessionAlreadyExists" and read additionalProperties.blockingSessionId.

Actions

(params: { encounterId: string; emrEncounterId?: string; multilingual?: boolean }) => Promise<{ ambientSessionId: string; noteId: string }>

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

(params: { ambientSessionId: string }) => Promise<void>

Cancels a remote ambient session that is blocking create in another Suki product. Pass the blockingSessionId from a sessionAlreadyExists error. Available before a local session exists.

(params: { ambientSessionId: string }) => Promise<void>

Ends a remote ambient session that is blocking create in another Suki product so captured audio can be processed. Pass the blockingSessionId from a sessionAlreadyExists error.

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,
    noteId, // New in v0.3.0
    session: { create, isPending, isSuccess, error }
  } = useAmbient();

  // Create the session when component mounts
  useEffect(() => {
    create({
      encounterId: 'your-encounter-id',
      // Pass emrEncounterId to share the note across Ambient products
      emrEncounterId: '6ec3920f-b0b1-499d-a4e9-889bf788e5ab', // New in v0.3.0
    });
  }, [create]);

  // Pass the session ID to parent once creation succeeds
  useEffect(() => {
    if (isSuccess && ambientSessionId) {
      onSessionReady({ ambientSessionId, noteId });
    }
  }, [isSuccess, ambientSessionId, noteId, 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:

Initializes the hook - Gets the useAmbient hook and its return values.
Creates session on mount - Automatically calls create({ encounterId, emrEncounterId }) when the component loads.
Handles loading state - Shows a loading message while isPending is true.
Handles success - Passes the ambientSessionId and noteId to the parent component once ready.
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, emrEncounterId }) 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. Refer to Ambient interoperability to share the clinical note across Ambient APIs, Mobile SDK, and Web SDK.

Get Started

Concepts & Feature Guides

API Reference

Resources

Create Ambient Session

Configuration

Common use cases

useAmbient hook

Usage

Returns

How session creation works

What it returns

Session identifier

Status flags

Actions

Code example

Available tutorials

Build a Headless Ambient Recorder

Next steps

​Configuration

​Common use cases

​useAmbient hook

​Usage

​Returns

​How session creation works

​What it returns

​Session identifier

​Status flags

​Actions

​Code example

​Available tutorials

​Build a Headless Ambient Recorder

​Next steps

Configuration

Common use cases

useAmbient hook

Usage

Returns

How session creation works

What it returns

Session identifier

Status flags

Actions

Code example

Available tutorials

Build a Headless Ambient Recorder

Next steps