Skip to content

Web Component — <twai-avatar>

The drop-in path for any webpage. One <script> tag + one <twai-avatar> element. No framework, no build step, no Flutter runtime. Transport 0 (LiveKit) under the hood.

Package: @twai/web-component on npm. Repo: 2waiorg/twai-web-sdk · reference use: apps/embed in the toolkit.

Minimal use

<!doctype html>
<html>
<head><meta charset="utf-8" /><title>My page</title></head>
<body>
  <twai-avatar
    mint-url="https://my-app.com/api/mint"
    avatar-id="avt_441ad4d95906438490a85b79">
  </twai-avatar>

  <script type="module">
    import { defineTwaiAvatar } from 'https://unpkg.com/@twai/web-component';
    defineTwaiAvatar();
  </script>
</body>
</html>

That’s a complete working embed. defineTwaiAvatar() registers the Custom Element; the <twai-avatar> tag’s connectedCallback calls your mint-proxy URL on connect, joins the LiveKit room, renders the agent’s video + audio.

Attributes

Attribute	What
`mint-url`	Required. Your mint proxy’s `POST /v1/sessions` endpoint.
`avatar-id`	Required. The avatar to render.
`voice-id`	Optional. Overrides the mint-proxy default voice.
`idle-url`	Optional. Idle video shown before/during warm-up.
`stt-url`	Optional. STT endpoint for mic input (see BYO STT in @twai/mic).
`mic-auto-send`	Optional. If set, mic transcripts auto-send as user turns.

Events

<twai-avatar id="avatar" mint-url="/api/mint" avatar-id="avt_..."></twai-avatar>
<script type="module">
  import { defineTwaiAvatar } from 'https://unpkg.com/@twai/web-component';
  defineTwaiAvatar();

  const el = document.getElementById('avatar');
  el.addEventListener('ready', () => console.log('agent is live'));
  el.addEventListener('reply', (e) => console.log('reply:', e.detail.text));
  el.addEventListener('speaking', (e) => console.log('speaking:', e.detail.active));
  el.addEventListener('error', (e) => console.error('err:', e.detail));
</script>

Imperative API

await el.send('Say hello to the audience.');
await el.interrupt();
el.disconnect();

When to use this vs the full Web SDK

Use case	Best fit
Drop an avatar into a page you already have	Web Component (this page)
Marketing site, static HTML	Web Component
React / Next.js app	Web SDK with React
Need per-event wiring, custom UI chrome around the video	Web SDK vanilla TS
iOS / Android native	Flutter or iOS native

Links