​
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"}'
    data-recaptcha-key="YOUR_GOOGLE_RECAPTCHA_SITE_KEY"
></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
  • data-recaptcha-key - Google reCAPTCHA v3 site key for bot protection (Note: Only reCAPTCHA v3 is supported)

​
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 <head> tag: 
    <script src="https://www.google.com/recaptcha/api.js?render=YOUR_GOOGLE_RECAPTCHA_SITE_KEY"></script>
  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

​
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
  5. If reCAPTCHA is enabled, bot protection is automatically applied

​
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 src="https://www.google.com/recaptcha/api.js?render=YOUR_GOOGLE_RECAPTCHA_SITE_KEY"></script>
    <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!"
      data-recaptcha-key="YOUR_GOOGLE_RECAPTCHA_SITE_KEY"
    ></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"
  data-recaptcha-key="YOUR_GOOGLE_RECAPTCHA_SITE_KEY"
></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
  • 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 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

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Retell Callback Widget Example</title>
    <script src="https://www.google.com/recaptcha/api.js?render=YOUR_GOOGLE_RECAPTCHA_SITE_KEY"></script>
    <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"
      data-recaptcha-key="YOUR_GOOGLE_RECAPTCHA_SITE_KEY"
    ></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