View as Markdown Open in ChatGPT Open in Claude

Events

Run your own code when the session connects, the avatar speaks, or an error happens.

Event map

Lifecycle

Prop	Type	Default	Description
`start`Optional	`() => void`	No default	Session connected and is active. Safe to call speakText, play, etc.
`stop`Optional	`() => void`	No default	Session ended. Either from stop() or a disconnection.
`speaking`Optional	`() => void`	No default	Avatar began speaking and animating.
`interrupt`Optional	`() => void`	No default	Avatar speech was cut short via interrupt().
`ready`Optional	`() => void`	No default	Avatar has rendered on screen for the first time.
`error`Optional	`(error: AvatarError) => void`	No default	An error occurred. Check error.fatal to know whether the session survived.

Session and conversation data

Prop	Type	Default	Description
`notice`Optional	`(notice: SessionNotice) => void`	No default	A graceful, server-initiated message — a plan limit, a demo cap, a test key expiring. The avatar speaks it and the session then closes. Not an error.
`transcript`Optional	`(entries: TranscriptEntry[]) => void`	No default	The whole transcript, re-emitted as a snapshot on every change. Only fires when transcript.enabled is set.
`health`Optional	`(health: ConnectionHealth) => void`	No default	Connection health, re-emitted whenever the server reports stream health. Carries the per-service map and the blame-resolved concern the banner renders from.

notice is not error. A notice means the session is ending deliberately, and notice.message is written for your users — it is the same text the avatar just said out loud. Drive upgrade CTAs off notice; never off error.

tsx

useAvatarEvent("notice", (notice) => {
  if (notice.action === "upgrade") showUpgradeDialog(notice.message);
  if (notice.action === "add_key") showKeyPrompt(notice.message);
});

Subscribing with useAvatarEvent (recommended)

useAvatarEvent handles cleanup automatically when the component unmounts.

tsx

import { useAvatarEvent } from "@avatarfactory/react";

function MyComponent() {
  useAvatarEvent("start", () => console.log("Connected!"));
  useAvatarEvent("stop",  () => console.log("Disconnected."));

  useAvatarEvent("error", (error) => {
    if (error.fatal) {
      console.error("Session ended:", error.code);
    } else {
      console.warn("Session continues:", error.message);
    }
  });

  return <div>...</div>;
}

Subscribing with on/off (manual)

Use when you need to subscribe outside the component lifecycle, or group multiple events in one useEffect.

tsx

import { useAvatar } from "@avatarfactory/react";
import { useEffect } from "react";

function MyComponent() {
  const { on, off } = useAvatar();

  useEffect(() => {
    const onStart = () => console.log("Started");
    const onError = (err) => console.error(err.code, err.message);

    on("start", onStart);
    on("error", onError);

    return () => {
      off("start", onStart);
      off("error", onError);
    };
  }, [on, off]);

  return <div>...</div>;
}

Always return a cleanup function from useEffect that calls off for every on. Missing cleanup causes memory leaks and stale handlers firing after component unmount.

The error state on useAvatar is sticky: it stays set until the next start(), so you can render off it safely. The error event fires once, in real time — use useAvatarEvent("error", ...) when you need every occurrence (analytics, logging).

Examples

Live session badge

tsx

function LiveBadge() {
  const [isLive, setIsLive] = useState(false);

  useAvatarEvent("start", () => setIsLive(true));
  useAvatarEvent("stop",  () => setIsLive(false));

  return (
    <span className={isLive ? "text-green-400" : "text-white/30"}>
      {isLive ? "● Live" : "○ Offline"}
    </span>
  );
}

Session timer

tsx

function SessionTimer() {
  const [seconds, setSeconds] = useState(0);
  const timerRef = useRef<ReturnType<typeof setInterval>>();

  useAvatarEvent("start", () => {
    timerRef.current = setInterval(() => setSeconds((s) => s + 1), 1000);
  });

  useAvatarEvent("stop", () => {
    clearInterval(timerRef.current);
    setSeconds(0);
  });

  return <p className="text-white/50 text-sm">Session: {seconds}s</p>;
}

App Events & Page Awareness

Error Handling