@oration/widget

v0.0.8

Published

11 days ago

Embeddable chat widget for Oration AI agents

0High
0Medium
0Low

yash-oration

aayushdotjain

shashwatpurplesectors

utkarshpurplesectors

chat widget embed oration ai agent

@oration/widget

Embeddable conversation widget for Oration AI agents that can be used on any website.

Features

🚀 Zero Dependencies: Standalone widget that works on any website
🎨 Custom Element: Use via simple HTML tags (<oration-widget>)
⚡ Lightweight: Optimized UMD bundle with Tailwind CSS for fast loading
🔧 Easy Integration: Just add one script tag to your website
📱 Responsive: Works on desktop and mobile devices
🎯 TypeScript Support: Full type definitions included
💬 Multiple Conversation Types: Web, chat, and user selection modes
🔊 Voice Conversations: Real-time voice calls with audio controls
📊 Live Transcripts: Real-time conversation transcripts
🎛️ Conversation Selector: Let users choose their preferred communication method
🎚️ External Button Trigger: Trigger conversations from any custom button on your page
⚙️ Highly Customizable: Configurable appearance, behavior, and conversation flows
🎨 Modern Styling: Built with Tailwind CSS for consistent, modern design

Quick Start

Use the widget anywhere in your HTML:

<body>
    <oration-widget
        public-key="your-public-key"
        default-agent-id="your-agent-id">
    </oration-widget>
    <script src="https://unpkg.com/@oration/widget/dist/index.umd.js"></script>
</body>

Configuration

| Attribute | Type | Required | Description | |-----------|------|----------|-------------| | public-key | string | Yes | Your Oration workspace public key | | default-agent-id | string | Yes | The assistant/agent ID to use for conversations | | conversation-type | string | No | Conversation mode: "web", "chat", or "both" (default: "web") | | agent-language-id-map | JSON string | No | Map of language codes to agent IDs for multi-language support | | dynamic-variables | JSON string | No | JSON string of string key-value pairs (Record<string, string>) to pass as context variables to the agent | | size | string | No | Widget size: "tiny" or "full" (default: "full") | | logo | string | No | Custom logo URL to replace the default Oration logo | | animate-logo | boolean | No | Control logo spin animation on hover/connect. Default: true for default logo, false for custom logo | | main-label | string | No | Custom text to override the initial "Ready to start" status message |

Conversation Types

"web" - Direct web-based voice conversation (default behavior)
"chat" - Text-based chat interface with messaging
"both" - Shows conversation selector UI for user to choose between web/chat
undefined/null - Defaults to web mode directly (no selector shown)

Widget Sizes

"full" - Standard widget size with full UI elements (default: 360px width when expanded)
"tiny" - Compact widget size with condensed UI elements (260px width when expanded)
- Smaller text and spacing
- Condensed buttons and controls
- Optimized for minimal screen real estate

Examples

Basic Usage (Web Mode)

<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here">
</oration-widget>

Chat Mode

<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here"
    conversation-type="chat">
</oration-widget>

Tiny Size Widget

<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here"
    size="tiny">
</oration-widget>

User Choice Mode (Conversation Selector)

<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here"
    conversation-type="both">
</oration-widget>

Multi-Language Support

Enable automatic language selection by mapping languages to specific agents:

<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_english_agent_id"
    agent-language-id-map='{"en-US": "asst_english_agent_id", "es-ES": "asst_spanish_agent_id", "hi-IN": "asst_hindi_agent_id"}'>
</oration-widget>

When agent-language-id-map is provided, the widget shows a language selector that automatically switches between agents based on the selected language.

Agent ID Selection Logic: When both default-agent-id and agent-language-id-map are provided, the widget determines which agent to use with the following priority:

If agent-language-id-map is provided and not empty: Uses the language map for agent selection
- If the provided default-agent-id exists as a value in the language map, it will be used
- If the provided default-agent-id is not in the language map, the first agent ID from the map will be used
If agent-language-id-map is not provided or empty: Uses the default-agent-id directly

The language selector only appears when agent-language-id-map is provided and contains at least one language mapping.

Dynamic Variables

You can pass context variables to your agent using the dynamic-variables attribute. This is useful for passing user information or application state:

<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here"
    dynamic-variables='{"userId": "12345", "plan": "pro", "name": "John Doe"}'>
</oration-widget>

These variables will be available to your agent during the conversation.

Programmatic Updates

You can also update dynamic variables programmatically using JavaScript. This is useful for Single Page Applications (SPAs) or when user state changes without a page reload.

const widget = document.querySelector('oration-widget');

// Update variables at any time
widget.setAttribute('dynamic-variables', JSON.stringify({
    userId: "67890",
    plan: "enterprise",
    currentPage: "/checkout"
}));
    currentPage: "/checkout"
}));

Custom Logo

You can replace the default Oration logo with your own brand logo using the logo attribute. You can also control the rotation animation using animate-logo.

<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here"
    logo="https://example.com/my-logo.png"
    animate-logo="true">
</oration-widget>

Animation Behavior:

Default Logo: Animation is enabled by default (animate-logo="true").
Custom Logo: Animation is disabled by default (animate-logo="false").
You can override these defaults by explicitly setting the animate-logo attribute.

Custom Text

You can customize the initial status text displayed in the widget using the main-label attribute.

<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here"
    main-label="Chat with our AI Assistant">
</oration-widget>

External Button Trigger

You can trigger conversations from any custom button on your page by giving it the ID oration-conversation-trigger:

<!-- Your custom button anywhere on the page -->
<button id="oration-conversation-trigger" class="my-custom-button">
    Start Conversation
</button>

<!-- Oration Widget (can be hidden or minimized) -->
<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here">
</oration-widget>

<script src="https://unpkg.com/@oration/widget/dist/index.umd.js"></script>

Key Features:

Any element with ID oration-conversation-trigger will trigger the widget conversation
Works with buttons, divs, links, or any clickable element
The widget itself can be hidden or styled to blend with your design
Only one button can be used to trigger the widget conversation

Styling Your Custom Button:

<style>
.my-custom-button {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
    border: none;
    padding: 12px 24px;
    border-radius: 8px;
    font-weight: 600;
    cursor: pointer;
    transition: transform 0.2s ease;
}

.my-custom-button:hover {
    transform: translateY(-2px);
}
</style>

<button id="oration-conversation-trigger" class="my-custom-button">
    🎯 Talk to Our AI Assistant
</button>

Complete Integration Example

<!DOCTYPE html>
<html>
<head>
    <title>My Website with Oration Widget</title>
</head>
<body>
    <h1>Welcome to My Website</h1>
    
    <!-- Custom trigger button -->
    <button id="oration-widget-button" style="background: #2563eb; color: white; padding: 10px 20px; border: none; border-radius: 6px; cursor: pointer;">
        Start AI Chat
    </button>
    
    <!-- Oration Widget with conversation selector and tiny size -->
    <oration-widget
        public-key="pk_your_public_key_here"
        default-agent-id="asst_your_assistant_id_here"
        conversation-type="both"
        size="tiny">
    </oration-widget>
    
    <!-- Load the widget script -->
    <script src="https://unpkg.com/@oration/widget/dist/index.umd.js"></script>
</body>
</html>

Theme Customization

The widget supports comprehensive theme customization through user-friendly theme keys that make it easy to customize colors without technical knowledge.

User-Friendly Theme Keys

The widget uses intuitive theme keys that map to different UI elements:

Base Theme Keys

base - Primary background color
base_hover - Hover state for interactive elements
base_active - Active/pressed state
base_border - Border colors
base_subtle - Subtle text and secondary elements
base_primary - Primary text color
base_error - Error states and destructive actions

Accent Theme Keys

accent - Primary accent color (buttons, highlights)
accent_hover - Accent hover state
accent_active - Accent active/pressed state
accent_border - Accent borders
accent_subtle - Subtle accent elements
accent_primary - Text on accent backgrounds

Theme Configuration

You can customize the widget theme using the theme attribute with JSON:

<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here"
    theme='{"base": "#ffffff", "accent": "#2563eb"}'>
</oration-widget>

Complete Theme Example

<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here"
    theme='{
        "base": "#ffffff",
        "base_hover": "#f8fafc",
        "base_active": "#f1f5f9",
        "base_border": "#e2e8f0",
        "base_subtle": "#64748b",
        "base_primary": "#0f172a",
        "base_error": "#ef4444",
        "accent": "#2563eb",
        "accent_hover": "#1d4ed8",
        "accent_active": "#1e40af",
        "accent_border": "#1e3a8a",
        "accent_subtle": "#64748b",
        "accent_primary": "#ffffff"
    }'>
</oration-widget>

Built-in Theme Presets

The widget includes several built-in theme presets:

Default: Clean blue theme
Midnight: Dark theme with purple accents
Rose: Light theme with pink accents
Indigo: Professional indigo theme
Slate: Neutral gray theme
Amber: Warm orange/yellow theme
Emerald: Fresh green theme

Theme Color Format

All theme colors should be provided as hex values (e.g., #ffffff, #2563eb). The widget automatically converts these to the appropriate internal format.

Partial Theme Customization

You don't need to specify all theme keys. The widget will use default values for any missing keys:

<!-- Only customize accent colors -->
<oration-widget
    theme='{"accent": "#10b981", "accent_hover": "#059669"}'
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here">
</oration-widget>

Built-in Design System

Modern UI: Clean, professional design with Tailwind CSS
Responsive Layout: Adapts seamlessly to desktop and mobile devices
Consistent Styling: Follows modern design principles and accessibility standards
Isolated Styles: Shadow DOM prevents CSS conflicts with your website
Theme Inheritance: Intelligent color mapping ensures consistent appearance

Widget States

The widget automatically handles different visual states using your theme colors:

Minimized: Circular button with hover effects
Expanded: Full conversation interface
Loading: Smooth loading animations
Active Call: Visual indicators for ongoing conversations
Conversation Selector: Clean interface for choosing conversation types

Development

Setup

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build library
pnpm build

# Test standalone version
pnpm preview

Project Structure

src/
├── index.tsx          # Main Widget component (React)
├── embed.tsx          # Custom element wrapper for script tag usage
└── styles.css         # Widget styles

Testing

Development: Run pnpm dev and visit http://localhost:3001
Standalone: Open test-standalone.html to test script tag integration
Production: Build with pnpm build and test the generated dist/index.umd.js

Browser Support

Modern browsers (Chrome, Firefox, Safari, Edge)
IE11+ (with polyfills)
Mobile browsers (iOS Safari, Chrome Mobile)

License

ISC

Support

For support and questions, please contact the Oration AI team.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@oration/widget

Features

Quick Start

Configuration

Conversation Types

Widget Sizes

Examples

Basic Usage (Web Mode)

Chat Mode

Tiny Size Widget

User Choice Mode (Conversation Selector)

Multi-Language Support

Dynamic Variables

Programmatic Updates

Custom Logo

Custom Text

External Button Trigger

Complete Integration Example

Theme Customization

User-Friendly Theme Keys

Base Theme Keys

Accent Theme Keys

Theme Configuration

Complete Theme Example

Built-in Theme Presets

Theme Color Format

Partial Theme Customization

Built-in Design System

Widget States

Development

Setup

Project Structure

Testing

Browser Support

License

Support