Widget SDK

Overview

The Oration Widget SDK is a lightweight, embeddable conversation widget that enables you to integrate AI voice agents directly into any website. With zero dependencies and simple HTML integration, add powerful conversational AI capabilities to your site in minutes.

Zero dependencies

Standalone widget that works on any website without external dependencies

Multiple conversation types

Support for web calls, chat, and user selection modes

Custom element

Simple HTML tag integration with <oration-widget>

Highly customizable

Comprehensive theme system and configuration options

Quick start

Add the widget to your website with just 2 lines of code:

<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>

Widget initial view - Ready to talk button

Configuration

Required attributes

Attribute	Type	Description
`public-key`	string	Your Oration workspace public key
`default-agent-id`	string	The assistant/agent ID to use for conversations

Optional attributes

Attribute	Type	Default	Description
`conversation-type`	string	`"web"`	Conversation mode: `"web"`, `"chat"`, or `"both"`
`agent-language-id-map`	JSON string	-	Map of language codes to agent IDs for multi-language support
`size`	string	`"full"`	Widget size: `"tiny"` or `"full"`
`theme`	JSON string	-	Custom theme configuration

Conversation types

Web mode (default)

Direct web-based voice conversation with real-time audio.

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

Widget in voice conversation mode with live transcript

Chat mode

Text-based chat interface with messaging.

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

Widget in chat mode with text conversation

User choice mode

Shows conversation selector UI for users to choose between web and chat.

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

Widget conversation type selector - Voice or Chat options

Full size (default)

Standard widget size with full UI elements (360px width when expanded).

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

Tiny size

Compact widget size optimized for minimal screen real estate (260px width when expanded).

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

Tiny widget size during voice conversation

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>

Widget with language selector dropdown showing English and Hindi options

Agent selection logic

When both default-agent-id and agent-language-id-map are provided:

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’s used
- If the provided default-agent-id is not in the language map, the first agent ID from the map is 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 1 language mapping.

Theme customization

The widget supports comprehensive theme customization through user-friendly theme keys.

Theme keys

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

Basic theme example

<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>

Partial theme customization

You don’t need to specify all theme keys. The widget uses 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>

Widget with custom orange theme applied to chat interface

Features

🚀 Zero dependencies

Standalone widget that works on any website without external dependencies.

🎨 Custom element

Use via simple HTML tags with <oration-widget> custom element.

⚡ Lightweight

Optimized UMD bundle with Tailwind CSS for fast loading.

🔧 Easy integration

Just add 1 script tag to your website.

📱 Responsive

Works seamlessly on desktop and mobile devices.

💬 Multiple conversation types

Support for web calls, chat, and user selection modes.

🔊 Voice conversations

Real-time voice calls with audio controls and live transcripts.

📊 Live transcripts

Real-time conversation transcripts during calls.

🎛️ Conversation selector

Let users choose their preferred communication method.

⚙️ Highly customizable

Configurable appearance, behavior, and conversation flows.

🎨 Modern styling

Built with Tailwind CSS for consistent, modern design.

External button trigger

You can trigger the widget conversation from any external button on your page by giving it the ID oration-conversation-trigger. This allows you to integrate the widget with your existing UI elements.

<!DOCTYPE html>
<html>
<head>
    <title>My Website with Custom Trigger</title>
</head>
<body>
    <h1>Welcome to My Website</h1>
    
    <!-- Your custom button that will trigger the widget -->
    <button id="oration-conversation-trigger" class="my-custom-button">
        Start AI Conversation
    </button>
    
    <!-- Oration Widget (will be triggered by the external button) -->
    <oration-widget
        public-key="pk_your_public_key_here"
        default-agent-id="asst_your_assistant_id_here"
        conversation-type="web">
    </oration-widget>
    
    <!-- Load the widget script -->
    <script src="https://unpkg.com/@oration/widget/dist/index.umd.js"></script>
</body>
</html>

External trigger behavior

Any button or element with ID oration-conversation-trigger will automatically trigger the widget
The external button respects the widget’s current state (won’t trigger if already connecting)
Works with all conversation types (web, chat, both)
If conversation-type="both", clicking the external button will show the conversation selector
The widget’s built-in button still works alongside the external trigger

Complete integration example

<!DOCTYPE html>
<html>
<head>
    <title>My Website with Oration Widget</title>
</head>
<body>
    <h1>Welcome to My Website</h1>
    
    <!-- Oration Widget with conversation selector and custom theme -->
    <oration-widget
        public-key="pk_your_public_key_here"
        default-agent-id="asst_your_assistant_id_here"
        conversation-type="both"
        size="tiny"
        theme='{"accent": "#10b981", "accent_hover": "#059669"}'>
    </oration-widget>
    
    <!-- Load the widget script -->
    <script src="https://unpkg.com/@oration/widget/dist/index.umd.js"></script>
</body>
</html>

Browser support

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

Getting your keys

To use the widget, you need:

Public key: Get your workspace public key from the Oration AI Dashboard
Agent ID: Create an agent and copy its ID from the agents section

Need help?

Contact our team at developers@oration.ai for support with integration

Advanced configuration

Shadow DOM isolation

The widget uses Shadow DOM to prevent CSS conflicts with your website, ensuring consistent styling regardless of your site’s CSS.

Event handling

The widget handles all conversation events internally, providing a seamless user experience without requiring additional JavaScript.

Performance optimization

Lazy loading of conversation components
Optimized bundle size with tree shaking
Efficient memory management for long conversations

Troubleshooting

Verify the script tag is correctly placed
Check browser console for JavaScript errors
Ensure your public key and agent ID are valid

Styling issues

The widget uses Shadow DOM for style isolation
Custom themes should use the provided theme keys
Check that theme JSON is properly formatted

Conversation issues

Verify your agent is properly configured
Check that your workspace has sufficient credits
Ensure microphone permissions are granted for voice conversations

Make sure to keep your public key secure and only use it on authorized domains. Never expose private API keys in client-side code.

Get Started

Agents

Conversations

Brand Voice

Campaigns

Reports & Insights

Settings

Phone Numbers

​Overview

Zero dependencies

Multiple conversation types

Custom element

Highly customizable

​Quick start

​Configuration

​Required attributes

​Optional attributes

​Conversation types

​Web mode (default)

​Chat mode

​User choice mode

​Widget sizes

​Full size (default)

​Tiny size

​Multi-language support

​Agent selection logic

​Theme customization

​Theme keys

​Base theme keys

​Accent theme keys

​Basic theme example

​Complete theme example

​Partial theme customization

​Features

​🚀 Zero dependencies

​🎨 Custom element

​⚡ Lightweight

​🔧 Easy integration

​📱 Responsive

​💬 Multiple conversation types

​🔊 Voice conversations

​📊 Live transcripts

​🎛️ Conversation selector

​⚙️ Highly customizable

​🎨 Modern styling

​External button trigger

​External trigger behavior

​Complete integration example

​Browser support

​Getting your keys

Need help?

​Advanced configuration

​Shadow DOM isolation

​Event handling

​Performance optimization

​Troubleshooting

​Widget not loading

​Styling issues

​Conversation issues

Overview

Quick start

Configuration

Required attributes

Optional attributes

Conversation types

Web mode (default)

Chat mode

User choice mode

Widget sizes

Full size (default)

Tiny size

Multi-language support

Agent selection logic

Theme customization

Theme keys

Base theme keys

Accent theme keys

Basic theme example

Complete theme example

Partial theme customization

Features

🚀 Zero dependencies

🎨 Custom element

⚡ Lightweight

🔧 Easy integration

📱 Responsive

💬 Multiple conversation types

🔊 Voice conversations

📊 Live transcripts

🎛️ Conversation selector

⚙️ Highly customizable

🎨 Modern styling

External button trigger

External trigger behavior

Complete integration example

Browser support

Getting your keys

Advanced configuration

Shadow DOM isolation

Event handling

Performance optimization

Troubleshooting

Widget not loading

Styling issues

Conversation issues