​
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 <script> tag and uses the Retell public key system, allowing direct API calls from the frontend—no backend proxy required. The widget supports two modes:
  • Chat Widget: Text-based conversations using a chat agent
  • Callback Widget: Phone-based conversations using a voice agent
Retell Website Widget

​
Prerequisites

Before embedding either widget, you’ll need:
  1. Create an Agent:
    • For chat widget: Create a chat agent using the Create Chat Agent guide
    • For callback widget: Create a voice agent to handle phone conversations
  2. Get Your Credentials:
    • Your Retell Public Key
    • Your Retell agent ID (chat agent for chat widget, voice agent for callback widget)
    • For callback widget: Your Retell phone number

​
Chat Widget

The chat widget provides text-based conversations through a chat interface.

​
Setup

Add the following script tag to your HTML, within the <head> tag: 
<script
    id="retell-widget"
    src="https://dashboard.retellai.com/retell-widget.js"
    type="module"
    data-public-key="YOUR_RETELL_PUBLIC_KEY"
    data-agent-id="YOUR_CHAT_AGENT_ID"
    data-agent-version="YOUR_AGENT_VERSION"
    data-title="YOUR_CUSTOM_TITLE"
    data-logo-url="YOUR_LOGO_URL"
    data-color="YOUR_CUSTOM_COLOR"
    data-bot-name="YOUR_BOT_NAME"
    data-popup-message="YOUR_POPUP_MESSAGE"
    data-show-ai-popup="true"
    data-show-ai-popup-time="5"
    data-auto-open="false"
    data-dynamic='{"key": "value"}'
></script>

​
Chat Widget Attributes

Required:
  • data-public-key - Your Retell public key
  • data-agent-id - Your chat agent ID
Optional:
  • data-agent-version - Agent version (if unset, uses latest version)
  • data-title - Custom chat window title
  • data-logo-url - URL of your logo image
  • data-color - Hex color code for widget theme (e.g., “#FFA07A”)
  • data-bot-name - Bot name for popup messages
  • data-popup-message - Popup message before users open chat
  • data-show-ai-popup - Set to “true” to enable popup messages
  • data-show-ai-popup-time - Seconds to delay before showing popup (default: 0)
  • data-auto-open - Set to “true” to auto-open chat widget on page load
  • data-dynamic - JSON string with dynamic variables for the chat agent

​
How Chat Widget Works

  1. User clicks the chat widget button (displays a robot icon)
  2. Chat interface opens in a modal window
  3. User types messages and receives responses from the chat agent
  4. Chat sessions are automatically handled and persisted in localStorage

​
Testing Chat Widget

After adding the widget to your website:
  1. Load your website
  2. Click the floating button (bottom right, robot icon)
  3. Start a conversation with your agent

​
Example: Chat Widget

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Retell Chat Widget Example</title>
    <script
      id="retell-widget"
      src="https://dashboard.retellai.com/retell-widget.js"
      data-public-key="key_xxxxxxxxxxxxxxxxxxxxx"
      data-agent-id="agent_xxxxxxxxxxxxxxxxxxx"
      data-agent-version="0"
      data-title="Chat with us!"
    ></script>
  </head>
  <body></body>
</html>

​
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.
Retell Callback Widget

​
Setup

Add the following script tag to your HTML, within the <head> tag: 
<script
  id="retell-widget"
  src="https://dashboard.retellai.com/retell-widget.js"
  type="module"
  data-public-key="YOUR_RETELL_PUBLIC_KEY"
  data-agent-id="YOUR_VOICE_AGENT_ID"
  data-widget="callback"
  data-phone-number="YOUR_RETELL_PHONE_NUMBER"
  data-title="Request a Call"
  data-countries="US,CA,GB"
  data-tc="https://yoursite.com/terms"
  data-color="#FFA07A"
></script>

​
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

​
How Callback Widget Works

  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. The widget creates a phone call using the Retell API
  5. User receives a call from your specified phone number
  6. 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

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Retell Callback Widget Example</title>
    <script
      id="retell-widget"
      src="https://dashboard.retellai.com/retell-widget.js"
      data-public-key="key_xxxxxxxxxxxxxxxxxxxxx"
      data-agent-id="agent_xxxxxxxxxxxxxxxxxxx"
      data-widget="callback"
      data-phone-number="+15551234567"
      data-title="Request a Call"
      data-countries="US,CA,GB"
      data-tc="https://example.com/terms"
      data-color="#FFA07A"
    ></script>
  </head>
  <body></body>
</html>

​
Widget Behavior Summary

  • Chat Widget: Shows robot icon, opens chat interface for text conversations
  • Callback Widget: Shows phone icon, opens form to collect contact info and initiates phone call