> ## 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
> 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
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.
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`**. See [What it returns](#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.
```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
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.
```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({ 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 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({ 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
## 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.