Website widget

• Chat and voice widget (default): text chat, in-browser voice calls, or both in one window.
• Callback widget: collects the visitor’s name and phone number, then your voice agent calls them.

​

Video tutorial

​

When to use it

• Support or sales on your site: a visitor types a question, or taps Voice Assistant to talk to the agent without dialing a number.
• Voice demo on a landing page: show prospects your voice agent with a one-click browser call.
• Callback requests: a visitor leaves a phone number and your agent calls them right away, for example to qualify a lead or book an appointment.

​

Prerequisites

1. An agent for each channel you want to offer:
   • Text chat needs a chat agent.
   • In-browser voice calls need a voice agent.
   • The callback widget needs a voice agent and a Retell phone number to call from.
2. A Retell public key. If you restrict the key to specific domains, add the domain that hosts the widget.

​

Chat and voice widget

​

What do visitors see when they open the widget?

​

Set up the widget

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Retell chat and voice widget</title>
    <script
      id="retell-widget"
      src="https://dashboard.retellai.com/retell-widget-v2.js"
      data-public-key="key_xxxxxxxxxxxxxxxxxxxxx"
      data-voice-public-key="key_xxxxxxxxxxxxxxxxxxxxx"
      data-agent-id="agent_chat_xxxxxxxxxxxxxxx"
      data-voice-agent-id="agent_voice_xxxxxxxxxxx"
      data-title="How can we help?"
      data-color="#FFA07A"
    ></script>
  </head>
  <body></body>
</html>

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Retell voice widget</title>
    <script
      id="retell-widget"
      src="https://dashboard.retellai.com/retell-widget-v2.js"
      data-voice-public-key="key_xxxxxxxxxxxxxxxxxxxxx"
      data-voice-agent-id="agent_voice_xxxxxxxxxxx"
      data-title="Talk to us"
      data-fab-text="Call us now"
    ></script>
  </head>
  <body></body>
</html>

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Retell chat widget</title>
    <script
      id="retell-widget"
      src="https://dashboard.retellai.com/retell-widget-v2.js"
      data-public-key="key_xxxxxxxxxxxxxxxxxxxxx"
      data-agent-id="agent_chat_xxxxxxxxxxxxxxx"
      data-title="Chat with us!"
      data-popup-message="Hi! Need help? Chat with us."
    ></script>
  </head>
  <body></body>
</html>

​

How it works

1. The visitor clicks the floating button.
2. If both agents are set, they pick Voice Assistant or Chat Assistant. Otherwise the widget opens the one channel you configured.
3. Chat: the visitor types and the chat agent replies, with a typing indicator while a reply is pending. Chats are saved in the browser’s localStorage, so a returning visitor resumes their most recent chat.
4. Voice: the visitor starts the call, allows microphone access, and talks to the voice agent over WebRTC. The visitor can mute or hang up from the call screen. If the visitor closes the window mid-call, the call keeps running and they can reopen it to hang up.

​

Attributes

​

Colors

• The theme color uses data-color if set, otherwise data-theme-color.
• The accent color uses data-component-color if set, otherwise data-color.

​

Embed the widget in a page section

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Retell embedded widget</title>
  </head>
  <body>
    <div
      data-retell-widget="true"
      data-public-key="key_xxxxxxxxxxxxxxxxxxxxx"
      data-voice-public-key="key_xxxxxxxxxxxxxxxxxxxxx"
      data-agent-id="agent_chat_xxxxxxxxxxxxxxx"
      data-voice-agent-id="agent_voice_xxxxxxxxxxx"
      style="width: 100%; max-width: 420px; height: 600px"
    ></div>

    <script defer src="https://dashboard.retellai.com/retell-widget-embed.js"></script>
  </body>
</html>

• The container must have a height or min-height. With zero height, the widget is invisible and logs a warning in the browser console.
• Only the first element with data-retell-widget on the page is mounted.
• Attributes that control the floating button and popup message have no effect.

​

Callback widget

​

Set up the callback widget

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

​

Callback attributes

​

How the callback widget works

1. The visitor clicks the floating phone button.
2. They fill in first name, last name, and phone number, and accept the privacy agreement.
3. If reCAPTCHA is enabled, the submission is verified.
4. The widget creates a phone call from data-phone-number to the visitor, handled by your voice agent.

​

reCAPTCHA protection

1. Load the reCAPTCHA v3 script in your page’s <head>:
   <script src="https://www.google.com/recaptcha/api.js?render=YOUR_GOOGLE_RECAPTCHA_SITE_KEY"></script>
   
2. Add data-recaptcha-key="YOUR_GOOGLE_RECAPTCHA_SITE_KEY" to the widget.
3. Turn on reCAPTCHA for your public key in public key settings.

​

Test the widget

1. Load your page and click the floating button (or scroll to your container, for the embedded build).
2. For chat, send a message and check that the agent replies.
3. For voice, start a call, allow microphone access, and talk to the agent.
4. For callback, submit the form with your own number and wait for the call.

​

FAQ