@anam-ai/agent-widget

Embeddable video agent widget for Anam AI. Add a conversational AI avatar to any website with a single HTML snippet.

Quick Start

Add two lines to your HTML:

<anam-agent agent-id="your-persona-id"></anam-agent>
<script src="https://unpkg.com/@anam-ai/agent-widget" async></script>

The widget auto-registers the <anam-agent> custom element on load. No build step required.

Allowed origins: Your persona must have an allowed origin configured in Anam Lab widget settings for the domain you're embedding on, or "Allow everywhere" must be enabled. Without this, the widget will be blocked by default.

Installation

CDN (recommended for embedding)

<script src="https://unpkg.com/@anam-ai/agent-widget" async></script>

Also available via jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/@anam-ai/agent-widget" async></script>

npm (for bundlers)

npm install @anam-ai/agent-widget

import { registerWidget } from '@anam-ai/agent-widget';

registerWidget(); // registers <anam-agent>
registerWidget('my-agent'); // or use a custom tag name

Attributes

Configure the widget entirely via HTML attributes. All are optional except agent-id.

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | agent-id | string | — | Persona ID from Anam Lab. Required for streaming. | | session-token | string | — | Pre-created session token. Skips the /v1/auth/widget call when set (used by Lab preview). | | api-base-url | string | https://api.anam.ai | API endpoint override. | | layout | inline | floating | floating | Inline renders in-flow; floating overlays the page. | | initial-state | minimized | expanded | expanded | Floating layout only. Start as orb or expanded sheet. | | position | string | bottom-right | Corner preset (bottom-right, bottom-left, top-right, top-left) or custom bracket syntax. | | ui-mute-button | true | false | true | Show microphone mute toggle. | | ui-text-input | true | false | true | Show text message input. | | ui-captions | true | false | false | Show conversation captions. | | call-to-action | string | Talk to our assistant | Text on the start button. | | avatar-url | string | — | Override avatar thumbnail image URL. | | avatar-video-url | string | — | Override avatar preview video URL. | | agent-name | string | — | Override persona name displayed in the CTA. |

Custom Positioning

Beyond the four corner presets, use bracket syntax for pixel-level control:

<anam-agent agent-id="..." position="[top-20,right-0]"></anam-agent>
<anam-agent agent-id="..." position="[bottom-100,left-40]"></anam-agent>

Layout Modes

Floating (default)

Renders as a fixed-position overlay. Starts expanded or as a clickable orb depending on initial-state.

<anam-agent
  agent-id="your-persona-id"
  layout="floating"
  initial-state="minimized"
  position="bottom-right"
></anam-agent>

Inline

Renders in the normal document flow, filling its parent container.

<div style="width: 400px; height: 600px;">
  <anam-agent agent-id="your-persona-id" layout="inline"></anam-agent>
</div>

Configuration Priority

The widget merges configuration from three sources (highest priority wins):

1. HTML attributes — per-instance overrides set by the embedder
2. Server config — persona settings from Anam Lab (fetched via API)
3. Widget defaults — built-in fallbacks

How It Works

1. On load: The widget fetches persona metadata (avatar image, name, display config) from GET /v1/personas/:id/widget
2. On user click: Requests a session token from POST /v1/auth/widget, then starts a WebRTC stream via the Anam JS SDK
3. During session: Real-time video avatar with voice input, optional text input, and mute controls
4. On close: Stops the stream and cleans up resources

Events

The widget dispatches custom DOM events on the <anam-agent> element:

| Event | Payload | Description | |-------|---------|-------------| | anam-agent:session-started | { sessionId } | Stream connected | | anam-agent:session-ended | { sessionId, reason } | Stream ended | | anam-agent:message-received | { role, content } | Message from user or assistant | | anam-agent:message-sent | { content } | Text message sent | | anam-agent:expanded | {} | Widget expanded from orb | | anam-agent:collapsed | {} | Widget collapsed to orb | | anam-agent:error | { code, message } | Error occurred | | anam-agent:mic-muted | {} | Microphone muted | | anam-agent:mic-unmuted | {} | Microphone unmuted |

document.querySelector('anam-agent').addEventListener('anam-agent:session-started', (e) => {
  console.log('Session started:', e.detail.sessionId);
});

Development

Prerequisites

• Node.js 18+
• pnpm 10+

Setup

pnpm install

Dev Server

pnpm dev

Opens the playground at http://localhost:5173/playground/ with HMR. The playground provides a sidebar with controls for all widget attributes and a live preview area.

Set VITE_ANAM_AGENT_ID in .env to pre-fill the agent ID input.

Build

pnpm build

Outputs dual-format bundles to dist/:

• dist/index.js — ESM (for bundlers)
• dist/index.umd.js — UMD (for script tags)

All dependencies are bundled into the output (zero runtime externals).

Preview Production Build

pnpm preview

Builds and serves at http://localhost:4173/playground/preview.html using the UMD bundle.

Type Check

pnpm typecheck

Lint

pnpm lint

Architecture

• Preact — lightweight UI rendering (~4KB)
• Preact Signals — fine-grained reactive state for session lifecycle
• Shadow DOM — full CSS isolation from host page styles
• Web Components — <anam-agent> custom element via preact-custom-element
• Tailwind CSS — compiled and inlined into the Shadow DOM (no external stylesheets)
• Vite — library-mode build with esbuild minification

Browser Support

Modern browsers with Web Components and WebRTC support:

• Chrome / Edge 80+
• Firefox 63+
• Safari 13.1+