Skip to main content

​
Constructor

Two overloads: 
new AvaturnHead(options: AvaturnHeadConfig)
new AvaturnHead(rootElement: HTMLElement, options: AvaturnHeadConfig)
Pass a DOM element as the first argument to render the avatar into it on init(). Omit it and the avatar isn’t rendered until you call attachDOMNode(). 
import { AvaturnHead } from "@avaturn-live/web-sdk";

const root = document.querySelector<HTMLDivElement>("#avaturn-video")!;

const avatar = new AvaturnHead(root, {
  sessionToken: "<SESSION_TOKEN>",
  audioSource: true,
  immediatelyJoin: true,
  startAudioOff: false,
  preloadBundle: false,
  preconnect: false,
  keepAlive: false,
  apiHost: "https://api.avaturn.live",
});

await avatar.init();
​
rootElement
HTMLElement
Optional first positional argument. When passed, the avatar renders into this element on init(). Without it, call attachDOMNode() before rendering becomes visible.

​
Config

​
sessionToken
string
required
Per-session token from POST /api/v1/sessions. Must be minted on your backend.
​
audioSource
boolean
default:"false"
Requests microphone access and routes the user’s voice into the conversation engine. Required for voice-to-voice flows (OpenAI Realtime, Cartesia).
​
startAudioOff
boolean
default:"!audioSource"
Starts the session with the microphone muted. Defaults to the opposite of audioSource — voice-to-voice sessions start unmuted, text-echo sessions start muted.
​
immediatelyJoin
boolean
default:"true"
Joins the avatar room as soon as init() resolves. Set to false if you need a manual gap between init and join — then call join() yourself.
​
preloadBundle
boolean
default:"false"
Fetches the SDK runtime bundle eagerly. Reduces first-interaction latency at the cost of an extra network request on page load.
​
preconnect
boolean
default:"false"
Opens the stream connection before init() completes. Trades a small amount of bandwidth for faster time-to-first-frame.
​
keepAlive
boolean
default:"false"
Keeps the local SDK state alive during user inactivity. With the default (false), the SDK tears down its local Daily call object after 5 minutes idle and emits the idle event. The backend session terminates separately via user_absent_timeout.
​
apiHost
string
default:"https://api.avaturn.live"
Override the API host. Rarely needed — when set, expose both ${apiHost}/api/v1 and ${apiHost}/_sdk/v0 (see Under the hood).