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

# Web SDK Integration Guide

> Mount the avatar in your frontend and wire up events.

The Web SDK renders an Avaturn avatar into a DOM element and bridges audio between the user's microphone and the active [conversation engine](/howtos/openai_realtime_api).

## 1. Install

```bash theme={null}
npm install @avaturn-live/web-sdk
```

## 2. Initialize

Create an `AvaturnHead` with a session token minted on your backend ([`POST /api/v1/sessions`](/api-reference/create-session)).

```typescript theme={null}
import { AvaturnHead } from "@avaturn-live/web-sdk";

const root = document.querySelector<HTMLDivElement>("#avaturn-video")!;
const avatar = new AvaturnHead(root, {
  sessionToken: "<token from backend>",
  audioSource: true, // request mic for voice-to-voice engines
});

await avatar.init();
```

<Tip>
  Make sure the DOM node exists before construction. In React/Vue use a `ref` and construct inside an effect; in Angular use `@ViewChild` and construct in `ngAfterViewInit`.
</Tip>

All constructor options: [Properties](/web-sdk/reference/properties).

## 3. Subscribe to events

```typescript theme={null}
avatar.on("avatar_started_speaking", () => {
  // e.g. show "speaking" indicator
});

avatar.on("avatar_ended_speaking", () => {
  // e.g. hide indicator
});
```

Full list: [Events](/web-sdk/reference/events).

## 4. Dispose

```typescript theme={null}
await avatar.dispose();
```

`dispose()` tears down local SDK state. The backend session terminates via `user_absent_timeout` after disconnection — to end it immediately call [`DELETE /api/v1/sessions/{id}`](/api-reference/terminate-session).

## Under the hood

The SDK talks to Avaturn through a private endpoint prefix `${apiHost}/_sdk/v0` (default host `https://api.avaturn.live`) authenticated with an `X-Session-Token` header. The session-room handshake is delegated to [Daily.co](https://daily.co/) over WebRTC.

For self-hosted deployments override `apiHost` ([Properties](/web-sdk/reference/properties#apihost)) and make sure both `${host}/api/v1` (public REST) and `${host}/_sdk/v0` (SDK-only) resolve.

## Driving speech manually (legacy)

If you push text from a backend instead of running a conversation engine, see [Legacy text-echo](/legacy/text-echo).