Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.uponai.com/llms.txt

Use this file to discover all available pages before exploring further.

The UponAI website widget is a production-ready, customizable widget for any website, powered by the UponAI API. Embed it with a single <script> tag — 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

​
Prerequisites

  • For chat widget — A chat agent (Create Chat Agent guide)
  • For callback widget — A voice agent and a UponAI phone number
  • Your UponAI Public Key and Agent ID

​
Chat Widget

Provides text-based conversations through a floating chat interface.

​
Setup

Add this script tag inside your HTML <head>: 
<script
  id="retell-widget"
  src="https://dashboard.retellai.com/retell-widget.js"
  type="module"
  data-public-key="YOUR_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="#FFA07A"
  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_RECAPTCHA_SITE_KEY"
></script>

​
Chat Widget Attributes

Required:
AttributeDescription
data-public-keyYour UponAI public key
data-agent-idYour chat agent ID
Optional:
AttributeDescription
data-agent-versionAgent version (defaults to latest)
data-titleCustom chat window title
data-logo-urlURL of your logo image
data-colorHex color for widget theme (e.g. #FFA07A)
data-bot-nameBot name shown in popup messages
data-popup-messagePopup message shown before the user opens chat
data-show-ai-popupSet to "true" to enable popup messages
data-show-ai-popup-timeSeconds to delay before showing popup (default: 0)
data-auto-openSet to "true" to auto-open on page load
data-dynamicJSON string with dynamic variables for the agent
data-recaptcha-keyGoogle reCAPTCHA v3 site key for bot protection

​
Full Example

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

​
Callback Widget

Collects the user’s phone number and initiates an outbound call from your agent instead of a chat session.

​
Setup

<script
  id="retell-widget"
  src="https://dashboard.retellai.com/retell-widget.js"
  type="module"
  data-public-key="YOUR_PUBLIC_KEY"
  data-agent-id="YOUR_VOICE_AGENT_ID"
  data-widget="callback"
  data-phone-number="YOUR_UPONAI_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_RECAPTCHA_SITE_KEY"
></script>

​
Callback Widget Attributes

Required:
AttributeDescription
data-public-keyYour UponAI public key
data-agent-idYour voice agent ID
data-widgetMust be "callback"
data-phone-numberYour UponAI phone number that will place the outbound call
Optional:
AttributeDescription
data-titleCustom widget title
data-colorHex color for widget theme
data-countriesComma-separated country codes for the country selector (e.g. "US,CA,GB")
data-tcURL to your terms and conditions page
data-recaptcha-keyGoogle reCAPTCHA v3 site key

​
How It Works

  1. User clicks the floating phone icon (bottom right)
  2. A form appears collecting first name, last name, phone number, and privacy agreement
  3. On submit, the widget creates an outbound call via the UponAI API
  4. The user receives a call from your specified number
  5. The conversation is handled by your configured voice agent

​
Full Example

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

​
reCAPTCHA Protection

Both widgets support Google reCAPTCHA v3 for bot protection.
Only reCAPTCHA v3 is supported. v2 is not compatible.
1

Add the reCAPTCHA script

Include this in your HTML <head>:
<script src="https://www.google.com/recaptcha/api.js?render=YOUR_RECAPTCHA_SITE_KEY"></script>
2

Add the attribute

Add data-recaptcha-key="YOUR_RECAPTCHA_SITE_KEY" to your widget script tag.
3

Enable in dashboard

Enable reCAPTCHA protection for your public key in the UponAI Public Keys settings.