> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retell Website Widget
> Embed the Retell website widget on your site with a single script tag — supports chat, voice, and callback modes powered by your chat and voice agents.
## Overview
The Retell embeddable website widget is a production-ready, customizable, and secure widget for websites, powered by the Retell API. The widget is embeddable via a single `
```
### Chat Widget Attributes
**Required (at least one):**
* `data-public-key` - Your Retell public key (used for chat API)
* `data-voice-public-key` - Separate public key for voice/web call API. At least one of `data-public-key` or `data-voice-public-key` is required.
**Optional — Agent Configuration:**
* `data-agent-id` - Your chat agent ID (enables text chat)
* `data-voice-agent-id` - Your voice agent ID (enables real-time voice calls). When both `data-agent-id` and `data-voice-agent-id` are set, the widget displays a chooser screen letting users pick between voice and chat.
* `data-agent-version` - Agent version (if unset, uses latest version)
* `data-dynamic` - JSON string with dynamic variables for the chat agent (e.g., `'{"company": "Acme"}'`)
**Optional — Appearance:**
* `data-title` - Custom chat window title (default: `"Chat"`)
* `data-logo-url` - URL of your logo image
* `data-color` - Hex color code for widget theme (e.g., `"#FFA07A"`). Acts as a shorthand that sets both `data-theme-color` and `data-component-color`.
* `data-theme-color` - Hex color for the widget theme/background (default: `"#071a3e"`). Overrides `data-color` for the theme.
* `data-component-color` - Hex color for accent elements like buttons and links (default: `"#3E6AEF"`). Overrides `data-color` for components.
* `data-fab-text` - Text displayed on the floating action button (default: `"Need support?"`)
**Optional — Behavior:**
* `data-bot-name` - Bot name for popup messages (default: `"AI Assistant"`)
* `data-popup-message` - Popup message before users open chat
* `data-show-ai-popup` - Set to `"true"` to enable popup messages, `"false"` to disable (default: `"true"`)
* `data-show-ai-popup-time` - Seconds to delay before showing popup (default: `5`)
* `data-auto-open` - Set to `"true"` to auto-open chat widget on page load (default: `"false"`)
**Optional — Security & Branding:**
* `data-recaptcha-key` - Google reCAPTCHA v3 site key for bot protection (**Note: Only reCAPTCHA v3 is supported**)
* `data-white-label` - White-label token to hide "Powered by Retell" branding. Contact Retell to obtain your token.
### Color Customization
The chat widget supports flexible color customization through a fallback chain:
| Attribute | CSS Variable | Default | Description |
| ---------------------- | ------------------- | --------- | --------------------------------------------------- |
| `data-theme-color` | `--color-theme` | `#071a3e` | Widget theme/background color |
| `data-component-color` | `--color-component` | `#3E6AEF` | Accent color for buttons, links, etc. |
| `data-color` | — | — | Shorthand that sets both theme and component colors |
**Fallback logic:**
* `data-theme-color` falls back to `data-color` if not set
* `data-component-color` falls back to `data-color` if not set
This means you can use `data-color` alone for a simple single-color theme, or combine `data-theme-color` and `data-component-color` for fine-grained control.
### Voice + Chat Hybrid Mode
When both `data-agent-id` and `data-voice-agent-id` are provided, the widget enters **hybrid mode**:
1. Users see a **chooser screen** with "Voice Assistant" and "Chat Assistant" options
2. A **tab bar** at the bottom allows switching between voice and chat at any time
3. Voice calls use WebRTC for real-time audio with a built-in audio visualizer
4. Chat sessions are persisted locally and can be resumed
If only `data-agent-id` is set, the widget goes directly to the chat interface.
If only `data-voice-agent-id` is set, the widget goes directly to the voice call interface.
### reCAPTCHA Protection
The chat widget supports Google reCAPTCHA v3 for bot protection. **Important: Only reCAPTCHA v3 is supported.**
To enable reCAPTCHA:
1. Include the Google reCAPTCHA v3 script in your HTML `` tag:
```html theme={null}
```
2. Add the `data-recaptcha-key` attribute to your widget script with your reCAPTCHA v3 site key
3. Enable reCAPTCHA protection for your public key in the [Retell Public Keys settings](/accounts/public-keys)
### How Chat Widget Works
1. User clicks the chat widget button (displays the FAB button with customizable text)
2. If voice agent is configured, a chooser screen appears; otherwise, chat opens directly
3. **Text chat**: User types messages and receives responses from the chat agent. Chat sessions are automatically persisted in the browser's localStorage and can be resumed later.
4. **Voice calls**: User clicks "Voice Assistant" to start a real-time WebRTC voice call with the agent. A built-in audio visualizer displays the conversation in real time.
5. If reCAPTCHA is enabled, bot protection is automatically applied to new chat sessions and voice calls
### Testing Chat Widget
After adding the widget to your website:
1. Load your website
2. Click the floating button (bottom right)
3. If both agents are configured, choose between voice or chat mode
4. Start a conversation with your agent
### Example: Chat Widget (Text Chat Only)
```html theme={null}
Retell Chat Widget Example
```
### Example: Chat Widget (Voice + Chat Hybrid)
```html theme={null}
Retell Voice + Chat Widget Example
```
## Callback Widget
The callback widget collects user information and initiates a phone call instead of a chat session. This mode requires a voice agent to handle the phone conversation.
### Setup
Add the following script tag to your HTML, within the `` tag:
```html theme={null}
```
### Callback Widget Attributes
**Required:**
* `data-public-key` - Your Retell public key
* `data-agent-id` - Your voice agent ID (not chat agent)
* `data-widget="callback"` - Enables callback mode
* `data-phone-number` - Your Retell phone number that will make the outbound call
**Optional:**
* `data-title` - Custom widget title
* `data-color` - Hex color code for widget theme
* `data-countries` - Comma-separated country codes for country selector (e.g., "US,CA,GB")
* `data-tc` - URL to your terms and conditions page
* `data-recaptcha-key` - Google reCAPTCHA v3 site key for bot protection
### How Callback Widget Works
**Note:** The callback widget supports the same reCAPTCHA v3 protection as the chat widget. To enable it, follow the instructions in the [reCAPTCHA Protection](#recaptcha-protection) section above.
1. User clicks the callback widget button (displays a phone icon)
2. A form appears collecting:
* First name (required)
* Last name (required)
* Phone number (required)
* Privacy policy agreement checkbox (required)
3. User submits the form
4. If reCAPTCHA is enabled, the form submission is validated
5. The widget creates a phone call using the Retell API
6. User receives a call from your specified phone number
7. The conversation is handled by your configured voice agent
### Testing Callback Widget
After adding the widget to your website:
1. Load your website
2. Click the floating button (bottom right, phone icon)
3. Fill out the contact form
4. Submit and wait for the phone call
### Example: Callback Widget
```html theme={null}
Retell Callback Widget Example
```
## Widget Behavior Summary
* **Chat Widget (text only)**: Shows FAB button, opens chat interface for text conversations with persisted chat history
* **Chat Widget (voice + chat)**: Shows FAB button, displays chooser screen for voice calls or text chat with tab switching
* **Callback Widget**: Shows phone icon, opens form to collect contact info and initiates phone call