Confana Widget

A premium, highly-configurable React widget for embedding real-time conversational AI agents powered by the Confana AI Engine. Drop it into any React app and your users get a full voice + chat agent interface in minutes.

Supports streaming text responses, voice calling, multi-step tool execution, and human-in-the-loop confirmation modals — all with a pixel-perfect design that matches the Confana dashboard experience.

Features

| Feature | Description | |---|---| | 🎙️ Voice Calling | Real-time voice agent with VAD (Voice Activity Detection) and animated orb UI | | 💬 Streaming Chat | Smooth token-by-token streaming with markdown support | | 🎨 Full Theming | Light / Dark / Auto modes, custom colors for every element | | 🔒 CSS Isolation | Tailwind v4 styles scoped to .confana-widget-container — zero layout leakage | | 🧠 Human-in-the-Loop | Modal triggers for confirmations, user prompts, and security approvals from agent workflows | | 📦 Floating or Inline | Configurable floating launcher or embed inline in your own layout | | ⚡ Dual-Mode Selection | Let users choose voice or text on open, or lock to one mode | | 🔧 LLM Override | Override provider, model, and system prompt per widget instance | | 🗣️ TTS Override | Override voice engine and clone voice per widget instance |

Installation

npm install confana

React 18+ or 19+ is required:

npm install react react-dom

Quick Start

import { ConfanaWidget } from 'confana';
import 'confana/dist/confana.css';

export default function App() {
  return (
    <div>
      {/* The rest of your app */}

      <ConfanaWidget
        agentId="your-agent-id-from-dexel-dashboard"
        backendUrl="https://your-dexel-backend.com"
        aiEngineUrl="https://your-ai-engine.com"
        theme="light"
      />
    </div>
  );
}

The widget renders a floating launcher button in the bottom-right corner. Clicking it opens the full chat/voice interface.

Interaction Modes

The widget has three configurable interaction modes controlled via the voice and text props:

Dual-Mode (Default)

Both voice and text are true. When the widget opens, the user sees a selection screen to pick "Call AI agent" (voice) or "Text via Chat".

<ConfanaWidget agentId="..." backendUrl="..." voice={true} text={true} />

Voice Only

<ConfanaWidget agentId="..." backendUrl="..." voice={true} text={false} />

Launches directly into the voice calling interface.

Chat Only

<ConfanaWidget agentId="..." backendUrl="..." voice={false} text={true} />

Launches directly into the text chat interface.

Props Reference

Core Props

| Prop | Type | Default | Description | |---|---|---|---| | agentId | string | — | MongoDB ID of the deployed agent. The widget fetches its config automatically. | | agent | object | — | Pass a direct agent config object (bypasses the backend lookup). | | backendUrl | string | "http://localhost:5000" | Base URL of your Dexel dashboard backend. | | aiEngineUrl | string | "http://localhost:8001" | Base URL of your running Confana AI Engine. |

Appearance Props

| Prop | Type | Default | Description | |---|---|---|---| | theme | "light" \| "dark" \| "auto" | "light" | Visual theme. "auto" follows the OS preference. | | position | "bottom-right" \| "bottom-left" \| "top-right" \| "top-left" | "bottom-right" | Position of the floating launcher button. | | backgroundColor | string | — | CSS color override for the launcher and header background. | | messageTextColor | string | — | CSS color override for message text. | | messageBackgroundColor | string | — | CSS color override for assistant message bubble background. | | headerTitleColor | string | — | CSS color override for the header title text. | | headerSubtitleColor | string | — | CSS color override for the header subtitle text. | | styles | React.CSSProperties | — | Additional inline styles applied to the widget container. |

Content Props

| Prop | Type | Default | Description | |---|---|---|---| | title | string | agent name | Override the chat window title. | | subtitle | string | — | Override the chat window subtitle. | | launcherLabel | string | — | Tooltip text shown next to the floating launcher button. |

Mode Props

| Prop | Type | Default | Description | |---|---|---|---| | voice | boolean | true | Enable voice calling mode. | | text | boolean | true | Enable text chat mode. | | inline | boolean | false | Render the widget inline instead of as a floating overlay. |

Override Props

| Prop | Type | Default | Description | |---|---|---|---| | llm | string \| LLMConfig | — | Override LLM provider, model, or system prompt for this widget instance. | | tts | string \| TTSConfig | — | Override TTS engine or voice clone settings for this widget instance. |

Type Reference

LLMConfig

interface LLMConfig {
  provider?: string;      // e.g. "groq" | "gemini" | "openai" | "anthropic"
  model?: string;         // e.g. "gemini-2.5-flash" | "gpt-4o" | "llama-3.1-8b-instant"
  systemPrompt?: string;  // Override the agent's system prompt
}

TTSConfig

interface TTSConfig {
  ttsEngine?: string;             // e.g. "omnivoice" | "mms" | "qwen3"
  voiceCloneAudioS3Key?: string;  // S3 key of an uploaded voice clone audio file
  voiceCloneRefText?: string;     // Reference transcript for the voice clone audio
}

Advanced Usage

Custom LLM Model Per Widget

<ConfanaWidget
  agentId="..."
  backendUrl="..."
  llm={{
    provider: "gemini",
    model: "gemini-2.5-flash",
    systemPrompt: "You are a helpful support agent for Acme Corp."
  }}
/>

Custom Voice Per Widget

<ConfanaWidget
  agentId="..."
  backendUrl="..."
  tts={{
    ttsEngine: "omnivoice",
    voiceCloneAudioS3Key: "voices/my-custom-voice.wav",
    voiceCloneRefText: "Hello, this is my reference recording."
  }}
/>

Inline Mode

Embed the widget directly inside a container instead of as a floating launcher:

<div style={{ width: 400, height: 600, borderRadius: 12, overflow: 'hidden' }}>
  <ConfanaWidget
    agentId="..."
    backendUrl="..."
    inline={true}
    theme="dark"
  />
</div>

Full Custom Theme

<ConfanaWidget
  agentId="..."
  backendUrl="..."
  theme="dark"
  backgroundColor="#6d28d9"
  messageTextColor="#f0f0f8"
  messageBackgroundColor="#1c1c2e"
  headerTitleColor="#ffffff"
  headerSubtitleColor="#c4b5fd"
  title="Aria"
  subtitle="AI Support Agent"
  launcherLabel="Chat with Aria"
/>

CSS Import

Always import the bundled stylesheet alongside the component:

import 'confana/dist/confana.css';

This applies the widget's scoped Tailwind CSS. It will not affect styles outside the widget container.

Backend Requirements

The widget connects to two services:

| Service | Env | Purpose | |---|---|---| | Dexel Backend (backendUrl) | Node.js / Express | Serves agent config, manages sessions, streams chat responses | | AI Engine (aiEngineUrl) | FastAPI (Python) | Runs the LLM inference, voice processing, and tool execution |

Both services are part of the Dexel platform. See the Dexel Dashboard for setup instructions.

Browser Support

| Browser | Voice | Chat | |---|---|---| | Chrome / Edge | ✅ | ✅ | | Firefox | ✅ | ✅ | | Safari | ✅ | ✅ | | Mobile Chrome | ✅ | ✅ | | Mobile Safari | ✅ | ✅ |

Voice calling requires microphone permission. The browser will prompt the user on first use.

License

MIT © Confana