> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autocalls.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime voice SDK

> Embed a realtime browser voice session with an assistant using the web SDK

Use the browser SDK when you want a voice session inside your own web app, instead of the [website widget](/ai-assistants/web-widget).

The SDK is `@voice-session/web`. Your backend mints `{ url, token }` with your API key. The browser never sees the API key.

## Flow

1. Your backend calls [Create realtime session](/api-reference/realtime/create-session) with the assistant UUID.
2. You send `url` and `token` to the browser.
3. The SDK starts the microphone session and emits transcripts and agent state.

## Install

```bash theme={null}
npm i @voice-session/web
```

## Example

```ts theme={null}
import { RealtimeSession } from "@voice-session/web";

const session = new RealtimeSession({ url, token });

session.on("agent_state", (state) => {
  // connecting | listening | thinking | speaking | ended
});

session.on("transcript", ({ role, text, final }) => {
  if (final) {
    appendLine(role, text);
  }
});

session.on("error", (error) => {
  showError(error.message);
});

await session.start({ microphone: true });

// later
await session.end();
```

### Events

| Event         | Payload                                                              |
| ------------- | -------------------------------------------------------------------- |
| `transcript`  | `{ role: "user" \| "assistant", text: string, final: boolean }`      |
| `agent_state` | `"connecting" \| "listening" \| "thinking" \| "speaking" \| "ended"` |
| `level`       | Remote audio level from 0 to 1. Useful for a speaking indicator.     |
| `ended`       | Session finished                                                     |
| `error`       | `Error`                                                              |

## Limits

* 10 session creations per minute per API key.
* 10 concurrent sessions per account. Unused tokens count until they expire (15 minutes). Live website-widget voice sessions on the same account also count.
* A Call History row is created only after the browser connects. Unused tokens do not appear in Call History.

## Security

* Mint `url` and `token` only on your server.
* Tokens expire after 15 minutes.
* Do not accept a room name or media URL from the browser. Use only the values returned by Create realtime session.