TruGen Chat Widget

A React + Vite chat widget powered by LiveKit, available as a React component library, a script-tag embed, or an iframe embed.

Integration Options

Option 1: React Component Library (recommended for React apps)

The widget is published as @trugen/clara-ui. Install it from npm (or link locally) and use the <TrugenChat> component directly.

Install

npm install @trugen/clara-ui

Peer dependencies (install if not already present):

npm install react react-dom livekit-client @livekit/components-react

Usage

import { TrugenChat } from '@trugen/clara-ui';
// Optional: retained for compatibility; TrugenChat injects styles into Shadow DOM.
import '@trugen/clara-ui/style.css';

function App() {
  return (
    <TrugenChat
      agentId="your-trugen-agent-id"
    />
  );
}

Migrating from @truviz/widget

Replace the old package dependency, then update imports to use @trugen/clara-ui:

npm uninstall @truviz/widget
npm install @trugen/clara-ui

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | agentId | string | env var | TruGen agent identifier | | provider | 'trugen' \| 'qatrugen' \| 'clarasdr' \| 'qaclarasdr' | 'clarasdr' | Selects the hosted environment. Sets the API base URL and widget host automatically. Falls back to 'http://api.clarasdr.ai' if omitted. | | agentName | string | 'Clara' | Display name for the AI agent | | theme | 'dark' \| 'light' | 'dark' | UI theme | | defaultOpen | boolean | false | Start with the widget open | | position | 'left' \| 'right' \| 'center-mini' \| 'center-large' | 'center-mini' | Widget position | | connectionQuality | 'AUTO' \| 'HIGH' \| 'MEDIUM' \| 'LOW' | 'AUTO' | Avatar stream quality; AUTO uses LOW in compact view and MEDIUM in expanded view | | suggestedTopics | { label: string; message: string }[] | [] | Topics shown before chat starts | | functions | Record<string, CustomRpcFunction> | — | Custom RPC functions the AI agent can call | | disabledFunctions | string[] | — | Built-in function names to disable | | companyLogo | string | Built-in logo | Logo image URL | | title | string | 'TruGen AI' | Header title | | subText | string | 'Bringing Your AI Agents to Life' | Header subtitle | | defaultTheme | 'dark' \| 'light' | 'dark' | Fallback theme when theme is not set | | accentColor | string (CSS color) | '#3a63de' | Accent color | | startChatButtonText | string | 'Start Chat' | Button text on closed bubble | | onReady | () => void | — | Callback after widget mounts |

Building the Library

npm run build:lib

Produces dist-lib/trugen-chat.js (ES module), a compatibility dist-lib/trugen-chat.css, and TypeScript declarations in dist-lib/types/. The component's active styles are injected into its Shadow DOM automatically.

Option 2: Script Tag Embed (for any website, no build tools needed)

A single self-contained JS file — all code and CSS are bundled together. The widget renders inside an open Shadow DOM root, so host-page selectors such as *, button, iframe, and global box-sizing rules cannot alter the widget or its booking view. No separate CSS file is needed; styles are injected into the shadow root at runtime. Supports custom RPC functions.

1. Build the project (npm run build) and deploy assets/trugen-chat-embed.js to a public URL.

2. Add the snippet to the customer site:

<script>
  window.TrugenWidget = {
    agentId: 'your-trugen-agent-id',
    provider: 'clarasdr', // 'trugen' | 'qatrugen' | 'clarasdr' | 'qaclarasdr'
  };
</script>
<script src="https://app.clarasdr.ai/assets/trugen-chat-embed.js" async></script>

If you want manual control, set autoInit: false and call window.TrugenWidget.init() when ready.

Option 3: Iframe Embed (full style isolation)

For sites where CSS isolation is critical. Uses trugen-chat.js to load the widget inside an iframe.

<script
  src="https://app.clarasdr.ai/trugen-chat.js"
  data-provider="clarasdr"
  data-theme="dark"
  data-position="bottom-right"
  data-width="420px"
  data-height="720px"
></script>

Or configure via JS:

<script>
  window.TrugenWidget = {
    provider: 'clarasdr', // 'trugen' | 'qatrugen' | 'clarasdr' | 'qaclarasdr'
    theme: 'dark',
    position: 'bottom-right',
    width: '400px',
    height: '600px'
  };
</script>
<script src="https://app.clarasdr.ai/trugen-chat.js"></script>

| Attribute | Default | Description | |-----------|---------|-------------| | data-provider | — | Provider key (trugen, qatrugen, clarasdr, qaclarasdr). Automatically sets the widget host URL. Takes priority over data-widget-url when neither is set. | | data-widget-url | Provider host /embed.html or current origin | Explicit URL to hosted embed.html. Overrides provider-derived URL. | | data-theme | dark | dark or light | | data-position | bottom-right | bottom-right, bottom-left, top-right, top-left | | data-width | 420px | Widget width | | data-height | 720px | Widget height | | data-offset-x | 16px | Horizontal offset | | data-offset-y | 16px | Vertical offset |

Note: Custom RPC functions are not supported in iframe mode since functions cannot be serialized across iframe boundaries. Use the script-tag embed or React library for custom RPC.

Custom RPC Functions

Custom RPC functions allow the AI agent to invoke your application logic at runtime. Each function receives an args object and must return { success: boolean; data?: unknown; error?: string }.

Functions are automatically registered as RPC methods on the LiveKit room alongside built-in functions (click_element, highlight_element, input_text, scroll_to_element, present_image, present_video, schedule_meeting, etc.).

You can also disable built-in functions you don't want the agent to use via disabledFunctions.