Skip to main content
The Web SDK renders an Avaturn avatar into a DOM element and bridges audio between the user’s microphone and the active conversation engine.

​
1. Install

npm install @avaturn-live/web-sdk

​
2. Initialize

Create an AvaturnHead with a session token minted on your backend (POST /api/v1/sessions). 
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();
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.
All constructor options: Properties.

​
3. Subscribe to events

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

avatar.on("avatar_ended_speaking", () => {
  // e.g. hide indicator
});
Full list: Events.

​
4. Dispose

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}.

​
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 over WebRTC. For self-hosted deployments override apiHost (Properties) 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.