Callback Widget
The Callback Widget is a small, embeddable form that lets your website visitors leave their phone number and get a call back from your AI agent — usually within seconds. Instead of asking visitors to dial in, the conversation comes to them.
This is the fifth widget type, alongside the Floating, Pill, Inline, and Popup widgets — but it works very differently. The other widgets start a voice conversation in the browser. The Callback Widget queues a real phone call placed by your agent through your outbound number.
When to Use It
| Scenario | Why Callback Widget Fits |
|---|---|
| Lead-gen landing pages | Visitor commits with a phone number, agent qualifies them in the next minute |
| High-intent product pages | "Talk to a specialist" without making the visitor dial |
| Mobile-first sites | One tap on the pill, no permission prompt, no headphones needed |
| Out-of-hours coverage | Visitor leaves a number after hours, agent dials when the queue opens |
| Reduced friction vs. forms | Visitors submit a single field and get an instant answer |
Eligibility
The Callback Widget requires three things on your account before it can be enabled:
| Requirement | Why |
|---|---|
| Paid plan (Starter or higher) | Outbound minutes consumed during the callback are billed per-minute |
| Verified outbound phone number assigned to the agent | The agent needs a real number to dial from |
| Verified email on your workspace | Confirms ownership before outbound calls are unlocked |
If any of these is missing, the Callback widget section in the agent's Widgets tab shows an alert telling you exactly what to fix. The widget stays disabled until all three are in place.
The Callback Widget is not available on the Free plan because it places outbound phone calls. All other widget types (Floating, Pill, Inline) remain free.
Setting It Up
1. Enable callback on the agent
- Open your agent and go to the Widgets tab.
- Scroll to the Callback widget section.
- Toggle "Enable callback widget" on.
- Configure:
- Retry attempts — how many times the agent retries if the visitor doesn't pick up (1–5, default 3).
- Retry interval — minutes between attempts (1–30, default 5).
- Widget language — the language the form, status messages, and country picker speak to your visitor in (14 languages available — see below).
- Theme — color scheme for the floating pill and dialog (uses the same theme palette as the other widgets).
- Save.
A live preview of the widget appears next to the settings so you can see your changes immediately — no need to deploy to test the look.
2. Copy the embed snippet
In the same section, copy the HTML snippet:
<hanc-ai-callback agent-id="YOUR_AGENT_ID"></hanc-ai-callback>
<script src="https://unpkg.com/hanc-webrtc-widgets@latest" async type="text/javascript"></script>
Paste it once into your website, typically right before </body>. The widget appears as a floating pill in the corner of the page.
The @latest tag means your site automatically picks up new widget versions when they ship. Pin to a specific version (e.g. hanc-webrtc-widgets@1.4.0) if you want full control over upgrades.
What the Visitor Sees
The widget walks visitors through four states:
| State | What the Visitor Sees |
|---|---|
| Form | Floating pill in the corner. Click to open. Country picker on the left, phone input on the right, submit button. |
| Queued | "You're in the queue — about N seconds until we call you." Updates live. |
| Dialing | "We're calling you now." Stays until the call connects or fails. |
| Completed / Failed | A short confirmation or a friendly error with a "reload the page to make another callback" hint. |
The form auto-validates the phone number against the chosen country's national format and refuses to submit unless the number is plausible.
Country coverage
The country picker covers Europe (EU + DACH + UK), North America (US + Canada), and a curated set of widely-supported additional countries. Each country shows its flag, name, and an example placeholder in the native format so the visitor knows what to type.
If a country your visitors use isn't listed, contact support@hanc.ai — coverage is expanded regularly.
HTML Attributes
The widget accepts these attributes on the <hanc-ai-callback> tag:
| Attribute | Required | Description |
|---|---|---|
agent-id | Yes | Your agent's unique identifier |
locale | No | Override the widget's UI language for this page (e.g. locale="de"). Useful if your site is multilingual and the page locale doesn't match the agent's default. |
theme | No | Override the color theme for this page |
position | No | Where the floating pill anchors (bottom-right, bottom-left, top-right, top-left) |
Anything you leave off falls back to whatever you configured on the agent in the dashboard.
Example: German page on a multilingual site
<hanc-ai-callback agent-id="YOUR_AGENT_ID" locale="de"></hanc-ai-callback>
<script src="https://unpkg.com/hanc-webrtc-widgets@latest" async></script>
The pill text, dialog labels, country picker, and status messages all switch to German. The agent itself still speaks in whatever language it's configured for — locale only affects what the visitor reads on the page.
Widget Language
The widget UI ships with 14 built-in languages:
| Code | Language |
|---|---|
en | English |
de | Deutsch |
fr | Français |
es | Español |
it | Italiano |
pt | Português |
pl | Polski |
cs | Čeština |
hu | Magyar |
tr | Türkçe |
kk | Қазақша |
zh | 中文 |
ru | Русский |
uk | Українська |
The agent picks its language from three places, in order of priority:
- The
locale="…"attribute on the embed (highest priority) - The Widget language set in the agent's Widgets tab
- English (default)
The widget language only affects on-screen text the visitor reads — labels, the country picker, status messages. The actual voice conversation happens in whatever language your agent is configured to speak.
Retry Behavior
If the visitor doesn't pick up on the first try, the agent waits the configured interval and dials again — up to the configured number of attempts.
- Attempts: 1–5 (default 3)
- Interval: 1–30 minutes (default 5)
The widget shows the visitor the status of each attempt. After all attempts fail, the widget switches to the "we couldn't reach you" state with a polite message.
Three attempts at five-minute intervals works well for most lead-gen pages — fast enough that the visitor is still browsing, gentle enough not to feel pushy. Bump it up if your audience tends to ignore unknown numbers.
One Callback per Page Load
Once a visitor submits their number, the widget locks itself for the rest of that page lifetime:
- Closing the dialog collapses the pill but does not reset the form.
- Reopening shows the current state (queued / dialing / completed / failed), not a fresh form.
- To make a second callback, the visitor needs to reload the page.
This prevents accidental duplicate submissions while a call is already on the way. If the visitor explicitly cancels their queued callback from the dialog (the "Cancel" button on the queued screen), the lock is released and they can re-submit immediately.
What happens if they reload mid-callback?
If a visitor reloads the page while the agent is still retrying their number, the widget detects that an active callback for the same number already exists and silently reconnects to it — no duplicate dial, no second queue entry. The visitor just sees their existing status pick up where it left off.
Concurrency and Throughput
A single agent can have up to 10 callbacks in flight at the same time. Submissions beyond that wait in the queue and are dialed as capacity frees up.
The agent-released-then-dial loop drains the queue continuously — most visitors are dialed within a few seconds of submitting if you're not near the concurrency cap.
There is a per-number rate limit (a number can only be queued a handful of times per hour for the same agent) to prevent abuse. Visitors who hit it see a friendly "we'll be in touch shortly" message instead of the queued screen.
Live Preview in the Dashboard
The Widgets tab shows a live preview of the callback widget next to the settings. Any change you make — theme, language, retry numbers — updates the preview instantly. You don't have to deploy your site to see how the widget will look.
The preview uses a mock manifest with the full country list and demo eligibility, so the widget renders even on plans where outbound callbacks aren't available yet.
Embedded Tracking
The widget emits the same call-start and call-end events as the other widgets. Listen for them in JavaScript if you want to fire your own analytics:
const widget = document.querySelector('hanc-ai-callback');
widget.addEventListener('call-start', () => {
// Visitor's callback was just connected — track as conversion
});
widget.addEventListener('call-end', () => {
// Callback finished — track duration, outcome, etc.
});
Plan Availability
| Plan | Callback Widget |
|---|---|
| Free | Not available (requires outbound calling) |
| Starter / Pro / Business / Enterprise | Available |
All paid plans get the same widget feature set. Per-call cost follows your normal outbound rate — see Billing.
Related
- Website Widgets — Floating, Pill, Inline, and Popup widget types for in-browser conversations
- Settings — Agent-level call settings including Max Call Duration that also caps callbacks
- Phone Numbers — Connect the outbound number your callback widget will dial from
- FAQ — Common questions and edge cases