@streamoji/avatar-widget

Plug-and-play avatar widget for token-based AI conversations. Use the React component in your app or drop in the script-tag (web) build on any HTML page—no React required.

Installation

npm install @streamoji/avatar-widget

Peer dependencies (install if not already present):

npm install react react-dom three @react-three/fiber @react-three/drei

Usage

import { AvatarWidget } from "@streamoji/avatar-widget";
import "@streamoji/avatar-widget/styles.css";

function App() {
  return (
    <AvatarWidget
      agentId="YOUR_AGENT_ID"
      onNavigationRequested={(url) => window.open(url, "_blank")}
    />
  );
}

With optional user prefill and avatar gender:

import { AvatarWidget } from "@streamoji/avatar-widget";
import "@streamoji/avatar-widget/styles.css";

function App() {
  const user = useCurrentUser(); // your auth

  return (
    <AvatarWidget
      agentId="YOUR_AGENT_ID"
      presetUserDetails={
        user
          ? { name: user.displayName, email: user.email, phone: user.phone }
          : undefined
      }
      onNavigationRequested={(url) => window.open(url, "_blank")}
    />
  );
}

Web flow (script tag, no React)

You can embed the widget on any HTML page without a React app. Use the UMD build and call the global init.

1. Build the UMD bundle (if you’re developing the package; otherwise use the published dist):

npm run build:html

2. Include the script and styles in your HTML:

<link rel="stylesheet" href="path/to/avatar-widget.umd.css">
<script src="path/to/avatar-widget.umd.js"></script>

For npm installs, the files are in node_modules/@streamoji/avatar-widget/dist/ (e.g. avatar-widget.umd.js, avatar-widget.umd.css). You can copy them to your static assets or point your bundler at them.

3. Initialize the widget (e.g. before </body>):

<script>
  StreamojiLeadsAvatarWidget.init({ agentId: "YOUR_AGENT_ID" });
</script>

If you don’t add a container, the widget creates one fixed at the bottom-right of the page. To control placement, add a div with id streamoji-leads-avatar-widget-root where the widget should mount:

<div id="streamoji-leads-avatar-widget-root"></div>
<script>
  StreamojiLeadsAvatarWidget.init({ agentId: "YOUR_AGENT_ID" });
</script>

Session UID generation uses the Web Crypto API and requires a secure context (HTTPS or localhost). On plain HTTP, HMAC-based session IDs will not be available.

Web init options

| Option | Type | Description | |--------|------|-------------| | agentId | string | Agent ID; widget fetches config (and records visit) and uses it for chat/STT. |

Props (React)

| Prop | Type | Description | |------|------|-------------| | agentId | string | Agent ID to fetch config and for chat/STT. | | onNavigationRequested | (url: string) => void | Called when the agent requests a link; if not provided, links open in a new tab. | | avatarGender | "male" \| "female" | Gender of the avatar for idle animations. Defaults to "male". | | presetUserDetails | UserDetails \| undefined | Optional user details (name, email, phone) to identify logged-in users and skip lead capture. |

UserDetails

interface UserDetails {
  name?: string;
  email?: string;
  phone?: string;
}

Publishing

From the repo root:

cd packages/avatar-widget
npm run build       # React build
npm run build:html  # optional: UMD bundle for web/script-tag usage (or use npm run build:all)
npm version patch   # or minor / major
npm publish --access public

Scoped packages require --access public if the scope is not on a paid npm plan.