@ariaflowagents/widget

Embeddable chat widget for the AriaFlow Universal Inbox.

Installation

Include the widget script on your website:

<script src="https://cdn.yourdomain.com/widget/v1.js"></script>

Usage

Method 1: Agent Resolution (Recommended)

Use agent-url (HTTP base URL) and agent-id to dynamically resolve agent configuration:

<ariaflow-widget
  agent-url="https://your-api-endpoint.com"
  agent-id="support"
  position="bottom-right"
  theme="light"
  title="Chat with us"
  subtitle="We're here to help!">
</ariaflow-widget>

The widget will:

1. Call GET https://your-api-endpoint.com/api/agent/support
2. Receive WebSocket URL and agent configuration
3. Connect to the resolved WebSocket endpoint

Method 2: Legacy Direct Connection

For backward compatibility with fallback logic:

<ariaflow-widget
  agent-url="wss://your-server.com"
  agent-id="support"
  position="bottom-right"
  theme="light">
</ariaflow-widget>

Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | agent-url | string | required | HTTP base URL for API calls | | agent-id | string | required | Agent identifier to resolve configuration | | widget-id | string | - | Legacy: Widget config ID | | api-url | string | - | Legacy: API endpoint for widget config | | position | string | "bottom-right" | Widget position: bottom-right, bottom-left, top-right, top-left | | theme | string | "light" | Theme: light or dark | | title | string | "Chat with us" | Header title | | subtitle | string | "We typically reply within minutes" | Header subtitle | | accent-color | string | "#14B8A6" | Primary accent color | | base-color | string | - | Base color for theming | | button-base-color | string | "#000000" | Button base color | | button-accent-color | string | "#FFFFFF" | Button accent color |

Programmatic Usage

Config-based Connection

import { WidgetClient } from '@ariaflowagents/widget';

// Initialize with API endpoint
const client = new WidgetClient('https://your-api-endpoint.com');

// Initialize widget with config ID
const config = await client.initWidget('widget_abc123');

Direct Agent Connection

import { WidgetClient } from '@ariaflowagents/widget';

// Initialize with direct agent WebSocket URL
const client = new WidgetClient(undefined, 'ws://localhost:3333/agents/chat');

// Initialize (no widget ID needed)
const config = await client.initWidget();

Common Methods (Both Approaches)

// Send message
await client.sendMessage('Hello!');

// Listen for messages
client.onMessages((messages) => {
  console.log('New messages:', messages);
});

// Listen for connection changes
client.onConnectionChange((connected) => {
  console.log('Connected:', connected);
});

// Get current messages
const messages = client.getMessages();

// Cleanup
client.dispose();

Architecture

The widget supports two connection architectures:

Config-based Architecture (Production)

Widget → API → Config DB → Agent WebSocket URL
    ↓                    ↓
Real-time chat     ← WebSocket ← Agent

1. Widget → API: Fetches configuration from /api/widget/:widgetId
2. API → Agent: Returns WebSocket URL for agent connection
3. Widget → Agent: Direct WebSocket connection for real-time chat

Direct Agent Architecture (Development/Debugging)

Widget → Agent WebSocket (Direct)
    ↓
Real-time chat

1. Widget → Agent: Direct WebSocket connection using agent-url prop
2. No config endpoint: Bypasses configuration for easier debugging

Benefits

Config-based (Production):

• Centralized widget management
• Dynamic agent routing
• Environment-specific configurations
• Security controls

Direct Agent (Development):

• Easier debugging and testing
• No config endpoint required
• Direct connection visibility
• Faster iteration during development

Development

# Install dependencies
bun install

# Build widget
bun run build

# Watch mode
bun run dev

# Type check
bun run typecheck

# Clean
bun run clean

Bundle Size

The widget is optimized to be under 50KB (gzipped) for fast loading.

License

MIT