Skip to main content
Quick Summary
The useAmbient hook creates a new ambient session container on Suki’s servers. You call session.create() to get a unique ambientSessionId that identifies your session.

The hook provides status flags (isPending, isSuccess, isError) so you can track the creation progress and update your UI accordingly. Once you have the ambientSessionId, you can use it with useAmbientSession to start recording.
Last updated:December 2025

​
Overview

The useAmbient hook creates a new ambient session in Suki’s backend. Think of it as the first step in your ambient documentation workflow. What it does: Before you can record audio or manage a session, you need to create a session container on Suki’s servers. This hook handles that creation process and gives you a unique ambientSessionId that identifies your session.

​
How It Works

The hook works in three simple steps:
  1. Call the hook - Initialize useAmbient() in your component
  2. Create the session - Call session.create() to request a new session from Suki’s backend
  3. Get the session ID - Once successful, use the ambientSessionId to proceed with recording
The hook provides status flags (isPending, isSuccess, isError) so you can track the creation progress and update your UI accordingly. 
const {
  ambientSessionId,
  session: {
    create,
    error,
    isError,
    isPending,
    isSuccess,
  },
} = useAmbient();

​
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()
function: () => void
Call this function to create a new ambient session. The function sends a request to Suki’s backend and updates all status flags automatically. You can call it when a component mounts, when a user clicks a button, or at any point in your workflow.

​
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();
  }, [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() 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.
You can also trigger session creation manually (e.g., on button click) instead of automatically on mount. Just call create() when the user performs an action.

​
Next Steps

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