Headless Mode: Build Your Own Widget UI
Hide the floating widget and start voice calls or chats from your own buttons with the widget's JavaScript methods and events.
Written By voiceaiwrapper
Last updated 19 days ago
Headless mode hides the floating widget completely. Your site keeps its own design, and your own buttons start and end voice calls or chats. The widget still does the work in the background: it connects the call, plays the agent's voice and handles the chat.
This is for developers. You add one attribute to the embed code and a few lines of JavaScript to your page.
Available on: plans that include Headless web widget. Without it, a widget with headless mode switched on shows nothing, the visitor's browser shows the alert "Widget headless mode isn't available for this widget." and the widget sends a widget.error event.
Headless mode works the same way for widgets on Vapi, Retell AI, ElevenLabs and VAW Native. The same methods and events work on every engine.
Before you start
- A widget with the modes you need. Your buttons can only start what the widget offers: a voice call needs voice mode and a voice agent, and chat needs chat mode. See Web Widgets: Voice, Chat or Both.
- The widget's embed code, from the builder's Embed Code tab. See Embed the Widget on a Website.
- Someone who can add JavaScript to the site.
You'll find a short summary in the webapp too: open the builder's Embed Code tab and scroll to Headless Mode (Bring Your Own UI).

Step 1: Hide the floating widget
Add hide-launcher to the <voiceai-widget> line of your embed code. Keep your own id and host:
<voiceai-widget id="YOUR_WIDGET_ID" host="YOUR_DOMAIN" hide-launcher></voiceai-widget>
<script defer src="https://YOUR_DOMAIN/widget/voiceai-widget.umd.js"></script>
The widget now shows nothing on the page, not even during a call. Audio still plays.
Step 2: Wait until the widget is ready
The widget loads its settings after the page loads. When it's ready, it sends a widget.ready event. Enable your buttons then.
Events are sent on the <voiceai-widget> element. Each event's details are in event.detail.
<button id="talk" disabled>Talk to us</button>
<button id="hang-up" disabled>End call</button>
<script>
const widget = document.querySelector('voiceai-widget');
widget.addEventListener('widget.ready', () => {
document.getElementById('talk').disabled = false;
});
</script>
Step 3: Call the methods from your buttons
<script>
document.getElementById('talk').addEventListener('click', () => widget.startCall());
document.getElementById('hang-up').addEventListener('click', () => widget.stopCall());
widget.addEventListener('voice.started', () => {
document.getElementById('hang-up').disabled = false;
});
widget.addEventListener('voice.ended', (event) => {
document.getElementById('hang-up').disabled = true;
console.log('Call lasted', event.detail.durationMs, 'ms');
});
</script>
Methods
If you ask for something the widget doesn't offer, for example startCall() on a chat-only widget, nothing starts and you get a widget.error event with the message "Voice mode is not enabled for this widget" (or "Chat mode is not enabled for this widget").
Events
Every voice.* and chat.* event also includes provider, the engine the widget runs on.
Step 4: Handle consent with your own notice
If the widget's Enable Consent setting is on, the widget can't show its own dialog while it's hidden. When a visitor who hasn't accepted yet tries to start something, you get widget.consent-required instead, and nothing starts.
Show your own notice. When the visitor agrees, call acceptConsent(). The widget saves the answer under the widget's Local Storage Key and starts the call or chat the visitor asked for.
<script>
widget.addEventListener('widget.consent-required', () => {
// Replace confirm() with your own notice or dialog.
if (confirm('This conversation is with an AI agent and may be recorded. Continue?')) {
widget.acceptConsent();
}
});
</script>
Only call acceptConsent() after the visitor has actually agreed. Calling it automatically skips the consent step for everyone. See Add Consent and Legal Notices.
Other ways to set it up
- Global shortcuts.
window.VoiceAIWidget.startCall(),stopCall(),sendChatMessage(text),endChatSession()andacceptConsent()do the same as the element's methods. They control the first widget on the page. - Start the widget from JavaScript. Instead of the
<voiceai-widget>element, you can load the script and callwindow.VoiceAIWidget.init('container-id', { id: 'YOUR_WIDGET_ID', host: 'https://YOUR_DOMAIN', hideLauncher: true }). It returns an object with the same methods plusdestroy(). With this method, events are sent on the container element. - Page variables (VAW Native). Pass details about the visitor with the
variablesattribute, or thevariablesoption ofinit. See Visitor Limits and Page Variables.
Full reference
The complete event reference, more examples and guides are in the Headless Mode documentation, the same link shown on the Embed Code tab.
Troubleshooting
An alert says "Widget headless mode isn't available for this widget."
An alert says "Widget headless mode isn't available for this widget."
Your plan doesn't include Headless web widget. Remove hide-launcher from the embed code to show the normal widget, or upgrade your plan. Test headless pages before they go live, since visitors see this alert too.
My button does nothing.
My button does nothing.
Check that:
- You waited for
widget.readybefore calling a method. Before the script has loaded, the element doesn't have the methods yet. - The widget offers the mode you're starting. Listen for
widget.errorto see the reason. - Consent isn't waiting. If you get
widget.consent-required, show your notice and callacceptConsent(). - No call is already running. The browser console shows "VoiceAIWidget: a call is already active" if one is.
Calls don't start for some visitors.
Calls don't start for some visitors.
Listen for voice.mic-permission-denied. It means the visitor blocked the microphone, so the call can't start. Show them how to allow it in their browser's site settings. Microphones only work on https:// pages.
Related articles
Was this helpful?
More in Web Widgets and Website Chat
Web Widgets: Voice, Chat or BothAdd a Widget to a VAW Native AgentCreate an Inbound Widget CampaignCustomize Layout, Branding and ColorsStill need help? Share an idea