> ## 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.
# Create Ambient Session
> Learn how to use the useAmbient hook to create an ambient session and obtain an ambientSessionId in the Headless Web SDK
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:
June 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
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
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](#code-example) below.
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](/headless-web-sdk/guides/error-handling).
## useAmbient hook
### Usage
Call **`useAmbient()`** with no arguments from a component under **`PlatformClientProvider`**. Destructure **`ambientSessionId`**, **`session.create`**, and the session status fields.
```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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](#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.
```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
A[Create ambient session] --> B{Request status}
B -->D[Receive SessionId]
D --> F[Pass ambientSessionId]
F --> H[Use ambientSessionId for recording]
style A fill:#FFF394,stroke:#D4A017,color:#000000
style D fill:#FFF394,stroke:#D4A017,color:#000000
style F fill:#FFF394,stroke:#D4A017,color:#000000
```
## What it returns
The hook returns the session identifier and status information about the creation request.
### Session identifier
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:
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.
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.
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.
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
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.
```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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 Initializing Suki Session...
;
}
// Show error if creation failed
if (error) {
return Error creating session: {error.message}
;
}
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](/headless-web-sdk/guides/hooks/ambient-session-hook) to start recording audio and manage the ambient session.