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:May 2026
The useAmbient hook allows you to create an ambient session on Suki’s servers. It returns an ambientSessionId and session.create() with status flags so you know when it is safe to hand that id to useAmbientSession for recording.

​
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 application is ready to start the workflow. Call session.create() to send the request to the Suki backend. While the request is in progress, monitor the session state using:
  • 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.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.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, documented under What it returns.

​
How session creation works

  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: When creation succeeds, use ambientSessionId for recording (typically 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()
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. 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.
Trigger session creation manually (e.g., on button click) instead of automatically on mount by calling create() when the user performs an action.

​
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.
Last modified on May 22, 2026