Integration Docs

Get started in 3 steps

Which one should I pick?

Take a look at this table first.

Which integration route should I pick?

Choose based on what your LLM outputs — text only goes A, BYO audio goes B. Both routes can mix in the same widget instance.

How to use in React / Vue?

Use our npm package — a real React / Vue <AIAvatar> component with a ref handle for speak() / lipsync(). Install: npm i @ai-avatar/embed-sdk

// Route A: your LLM returns text; we do TTS + lip-sync
// npm i @ai-avatar/embed-sdk
import { useRef, useState } from 'react';
import { AIAvatar, type AvatarInstance } from '@ai-avatar/embed-sdk/react';

export function AvatarCanvas() {
  const avatar = useRef<AvatarInstance>(null);
  const [ready, setReady] = useState(false);

  // Your own input box submits → call YOUR LLM → drive the avatar
  async function onUserSend(text: string) {
    const reply = await myLLM(text);            // your own LLM
    const r = await avatar.current?.speak(reply); // platform TTS + lip-sync
    // r?.usage?.chars, r?.interrupted ...
  }

  return (
    <>
      {/* Your container — the avatar fills it 100%; size / position / radius via your CSS */}
      <div id="avatar-box" style={{ width: 360, height: 480, borderRadius: 16, overflow: 'hidden' }} />
      <AIAvatar
        ref={avatar}
        apiKey="YOUR_API_KEY"
        mount="#avatar-box"        // display-only canvas (passing mount auto-enables inline)
        onAvatarLoaded={() => setReady(true)}      // enable your input once the avatar is ready
        onSpeakingChange={(speaking) => {/* sync your UI */}}
      />
      {/* ...your own input box; call onUserSend on submit, disable until ready... */}
    </>
  );
}

// ↓ Replace with your own LLM call
async function myLLM(text: string) {
  const res = await fetch('/api/my-llm', { method: 'POST', body: JSON.stringify({ text }) });
  return (await res.json()).reply as string;
}

Complete parameter reference

All available parameters + types + defaults + descriptions, switch by integration method.

Widget control

Control the widget's visibility, shape, and lifecycle. show() / hide() toggle overall visibility, while expand() / collapse() switch between the bubble and full states — two independent dimensions.

Common error codes

LLM failure fallback — don't leave the avatar spinning

The avatar only speaks what you pass back. If your LLM times out or fails, handle it in your own UI — otherwise the avatar is left with no reply and the user just waits.

• On timeout / error, call speak('Sorry, something went wrong') so the avatar speaks a fallback line instead of going silent.
• Rapid-fire questions: speak / lipsync auto-interrupt the previous playback, but your own UI must dedupe / queue messages itself.
• Gate user input until onAvatarLoaded / avatar-loaded fires — otherwise the first reply may play audio before the avatar appears, with no lip-sync.

// your input handler → your LLM → drive the avatar
async function onUserSend(text) {
  try {
    const reply = await myCustomerLLM(text);
    widget.speak(reply);
  } catch (e) {
    widget.speak('Sorry, I hit a problem — please try again');  // fallback reply
  }
}

Security: always configure origin allowlist

Frontend embedding inevitably exposes the API key to browsers — an allowlist is the most effective anti-abuse measure.

Open a project's Embed Code page, find the Domain allowlist section, and add allowed origins (e.g. https://your-site.com). The backend validates the request's Origin header and rejects non-allowlisted origins.

• Exact match (including protocol and port) and *.example.com wildcards for subdomains; one per line
• Add http://localhost:3000 separately for dev — avoid wildcards
• One key per site makes revocation precise on leak