Skip to main content
DocumentationAPI ReferenceVideo Tutorials

Website Widgets

Embed your voice agent on any website so visitors can start a voice conversation directly from the browser. The Widgets tab provides embed codes, customization options, and domain security settings.

Widget Types​

Hanc.AI offers three widget types:

WidgetTag NameDescriptionBest For
Floating Widgethanc-ai-floating-callOrb button that floats over your pageAlways-visible call-to-action
Pill Widgethanc-ai-pill-callCompact pill-shaped buttonMinimal footprint, inline or floating placement
Inline Widgethanc-ai-inline-callFull-size call button embedded in page contentDedicated "Talk to Us" sections

Common Attributes​

All widget types support these core attributes:

AttributeRequiredDescriptionDefault
agent-idYesYour agent's unique identifier—
voice-service-urlNoOverride the voice service URLAuto-detected
api-base-urlNoOverride the API base URLAuto-detected

Display Attributes​

AttributeDescriptionValuesDefault
positionWidget position on the pagebottom-right, bottom-left, top-right, top-left, staticbottom-right
sizeWidget size in pixelsNumber120
themeColor theme nameSee Color Themesdefault

Button Text Attributes​

AttributeDescriptionDefault
button-start-textText shown on the idle button"Call"
button-connecting-textText shown while connecting"Connecting..."
button-end-textText shown during an active call—

Terms Attributes​

AttributeDescriptionDefault
terms-enabledEnable consent dialog before callfalse
terms-contentMarkdown-formatted consent text""
terms-urlLink to your Terms & Conditions page"https://hanc.ai/terms"
privacy-urlLink to your Privacy Policy page"https://hanc.ai/privacy"
info

Terms attributes set on the HTML element are overridden by the agent's widget settings fetched from the API, unless skip-fetch is set to true.

Sound Attributes​

AttributeDescriptionDefault
sound-enabledEnable call start/end soundstrue
sound-volumeSound effect volume0.25
sound-presetSound preset identifier"1"

Color Themes​

Customize widget appearance with 11 built-in color themes:

ThemeValue
Defaultdefault
Purplepurple
Blueblue
Cyancyan
Emeraldemerald
Amberamber
Tangerinetangerine
Roserose
Emberember
Blackblack
Whitewhite

Each theme has both dark and light variants. Set the theme via the theme attribute in the embed code, or configure it in the agent's widget settings.

Embed Examples​

Floating Widget​

<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

Floating Widget with Theme and Position​

<hanc-ai-floating-call
  agent-id="YOUR_AGENT_ID"
  theme="emerald"
  position="bottom-left"
  size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

Pill Widget​

<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

Inline Widget​

<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

Widget Events​

Widgets emit events that you can listen for in JavaScript:

EventDescription
status-changedFired when the call status changes
connectingCall is being established
connectedCall is active
idleNo active call
errorAn error occurred
audio-trackRemote audio track received (for visualization)
local-audio-trackLocal microphone audio track (for visualization)
microphone-enabledMicrophone was enabled
microphone-disabledMicrophone was disabled
call-startFired when a call starts successfully
call-endFired when the call ends

Example: Listening for Events​

const widget = document.querySelector('hanc-ai-floating-call');

widget.addEventListener('call-start', () => {
  console.log('Call started');
});

widget.addEventListener('call-end', () => {
  console.log('Call ended');
});

Technical Requirements​

Widgets require the visitor's browser to support:

  • WebGL 2.0 — for rendering
  • Web Audio API — for audio processing
  • WebRTC — for real-time voice communication

All modern browsers (Chrome, Firefox, Safari, Edge) support these technologies.

Domain Restrictions​

Control which websites can embed your agent widget.

Always Allowed Domains​

The following domains are always allowed regardless of configuration:

  • hanc.ai (and subdomains)
  • hanc.me (and subdomains)
  • localhost

Allow All Domains​

By default, your widget can be embedded on any website. Toggle "Allow all domains" in widget settings to restrict this.

Restrict to Specific Domains​

When restricted, add each domain that should be allowed:

  • Enter domain names without https:// (e.g., example.com)
  • Subdomains need separate entries (e.g., www.example.com, shop.example.com)
  • Ports can be specified (e.g., localhost:3000)
  • Maximum 50 domains can be whitelisted
Security

For production agents, restrict widgets to your own domains to prevent unauthorized embedding.

Terms & Conditions​

Enable a consent dialog before callers can start a conversation.

Configuration​

SettingDescription
Enable TermsToggle terms dialog on/off
Terms ContentMarkdown-formatted consent text shown to users (max 5,000 characters)
Terms URLLink to your full Terms & Conditions page
Privacy URLLink to your Privacy Policy page

When enabled:

  • Users see a consent dialog before starting a call
  • They must click "Agree" to proceed
  • Consent is stored locally in the browser
  • Reset Consent button clears stored consent for testing

Content Formatting​

Terms content supports Markdown formatting:

  • Use #### for headings
  • Use **bold** for emphasis
  • Use line breaks for readability