Widget SDK - Oration AI Documentation

Overview

The Oration Widget SDK is a lightweight, embeddable web component (<oration-widget>) that adds AI voice and chat agents to any website. No framework or build step required — just a script tag.

Quick start

<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

Getting your keys

Public key — copy your workspace public key from the Oration Dashboard
Agent ID — create an agent and copy its ID from the agents section

Configuration

Required attributes

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

Optional attributes

Attribute	Type	Default	Description
`conversation-type`	string	`"web"`	`"web"`, `"chat"`, or `"both"`
`agent-language-id-map`	JSON string	—	Map of BCP-47 language codes to agent IDs
`size`	string	`"full"`	`"full"` (380px) or `"tiny"` (260px)
`position`	string	`"bottom-right"`	`"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"`
`color-mode`	string	`"system"`	`"light"`, `"dark"`, or `"system"`
`theme`	JSON string	—	Custom theme colors (see Theme customization)
`dynamic-variables`	JSON string	—	`Record<string, string>` passed as session context to the agent
`logo`	string	—	URL of a custom logo to replace the default
`animate-logo`	boolean	`true` for default logo, `false` for custom	Control logo spin animation
`main-label`	string	—	Override the initial “Ready to start” label
`orb-color`	string	—	Hex color for the AI orb (e.g. `"#2563eb"`)
`require-terms-acceptance`	boolean	`false`	Show a terms acceptance gate before the first conversation
`terms-text`	string	—	Custom terms text (used when `require-terms-acceptance` is enabled)
`enable-dtmf`	boolean	`false`	Show a DTMF numpad during voice calls

Conversation types

Web mode (default)

Real-time voice conversation.

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

<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

Lets users pick between voice 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

Value	Width	Use case
`"full"` (default)	380px	Standard widget with full UI
`"tiny"`	260px	Compact, minimal footprint

Tiny widget size during voice conversation

Multi-language support

Map BCP-47 language codes to specific agent IDs. A language selector will appear in the widget when the map contains at least one entry.

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

If agent-language-id-map is provided, the map takes priority over default-agent-id
If default-agent-id exists as a value in the map, it is pre-selected
Otherwise the first entry in the map is used as the default

Dynamic variables

Pass context to your agent using the dynamic-variables attribute. Values must be a JSON object of string key-value pairs.

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

Variables are available in session metadata during the conversation. Common uses: user identification, current page context, subscription tier, A/B test variant.

Programmatic updates

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

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

Theme customization

Pass a JSON object to theme with any subset of the following keys. Missing keys fall back to defaults.

Theme keys

Key	Role
`base`	Primary background
`base_hover`	Hover state background
`base_active`	Active/pressed state background
`base_border`	Border color
`base_subtle`	Secondary / muted text
`base_primary`	Primary text
`base_error`	Error states
`accent`	Primary accent (buttons, highlights)
`accent_hover`	Accent hover
`accent_active`	Accent active/pressed
`accent_border`	Accent border
`accent_subtle`	Muted accent elements
`accent_primary`	Text on accent backgrounds

All values must be hex color strings.

<!-- Minimal: just override accent -->
<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here"
    theme='{"accent": "#2563eb"}'>
</oration-widget>

<!-- Full theme -->
<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>

Widget with custom orange theme applied to chat interface

Color mode

Use color-mode to force light or dark theme, or let the widget follow the user’s system preference:

<oration-widget color-mode="dark" ...></oration-widget>

External button trigger

Any element with id="oration-conversation-trigger" will open the widget when clicked. The trigger respects the widget’s current state (no-op while connecting).

<button id="oration-conversation-trigger">Start AI Conversation</button>

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

If conversation-type="both", the trigger shows the conversation type selector first.

Terms acceptance

Show a consent gate before the first conversation. Acceptance is stored in localStorage and won’t be shown again.

<oration-widget
    public-key="pk_your_public_key_here"
    default-agent-id="asst_your_assistant_id_here"
    require-terms-acceptance="true"
    terms-text="By continuing, you consent to the recording of this conversation.">
</oration-widget>

Troubleshooting

Widget not loading — check the browser console, verify the script tag is present, and confirm your public key and agent ID are correct. Styling issues — the widget uses Shadow DOM for style isolation. Custom styles must go through the theme attribute. No microphone access — browser microphone permissions must be granted for voice conversations. Conversation fails — verify the agent is configured and your workspace has sufficient credits.

Your public key is visible in client-side code. Only use it on authorized domains. Never expose private API keys in the browser.

Need help? Contact us at support@oration.ai

​Overview

​Quick start

​Getting your keys

​Configuration

​Required attributes

​Optional attributes

​Conversation types

​Web mode (default)

​Chat mode

​User choice mode

​Widget sizes

​Multi-language support

​Dynamic variables

​Programmatic updates

​Theme customization

​Theme keys

​Color mode

​External button trigger

​Terms acceptance

​Troubleshooting

Overview

Quick start

Getting your keys

Configuration

Required attributes

Optional attributes

Conversation types

Web mode (default)

Chat mode

User choice mode

Widget sizes

Multi-language support

Dynamic variables

Programmatic updates

Theme customization

Theme keys

Color mode

External button trigger

Terms acceptance

Troubleshooting