> ## Documentation Index > Fetch the complete documentation index at: https://docs.oration.ai/llms.txt > Use this file to discover all available pages before exploring further. # Widget SDK > Embeddable conversation widget for Oration AI agents ## Overview The Oration Widget SDK is a lightweight, embeddable web component (``) that adds AI voice and chat agents to any website. No framework or build step required — just a script tag. ## Quick start ```html theme={null} ```

Widget initial view - Ready to talk button

## Getting your keys 1. **Public key** — copy your workspace public key from the [Oration Dashboard](https://www.oration.ai/app) 2. **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](#theme-customization)) | | `dynamic-variables` | JSON string | — | `Record` 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. ```html theme={null} ```

Widget in voice conversation mode with live transcript

### Chat mode Text-based chat interface. ```html theme={null} ```

Widget in chat mode with text conversation

### User choice mode Lets users pick between voice and chat. ```html theme={null} ```

Widget conversation type selector - Voice or Chat options

## Widget sizes | 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. ```html theme={null} ```

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. ```html theme={null} ``` Variables are available in session metadata during the conversation. Common uses: user identification, current page context, subscription tier, A/B test variant. ### Programmatic updates ```javascript theme={null} 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. ```html theme={null} ``` ```html theme={null} ```

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: ```html theme={null} ``` ## 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). ```html theme={null}

``` 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. ```html theme={null} ``` ## 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](mailto:support@oration.ai)