Skip to main content
Web Widgets and Website Chat

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).

Widget builder, right-hand column on the Embed Code tab, scrolled to the Headless Mode (Bring Your Own UI) card with the New and Not on every plan badges, the Methods list, the Events list and the Headless Mode documentation link.

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

MethodWhat it does
startCall()Starts a voice call. Only one call can run at a time.
stopCall()Ends the current voice call.
sendChatMessage(text)Sends a chat message. If no chat is open, it starts one first.
endChatSession()Ends the current chat.
acceptConsent()Records that the visitor accepted your consent notice and continues what they were starting. See Step 4.

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

EventWhen it's sentUseful details
widget.readyThe widget has loaded and the methods work.modes (voice, chat or both), provider
widget.consent-requiredThe visitor needs to accept consent first.pendingAction: voice or chat
widget.errorThe widget couldn't load, or a method can't run.message
voice.connectingA call is connecting.
voice.startedThe call is connected.
voice.endedThe call has ended (sent once per call, even if it never connected).durationMs
voice.mic-permission-deniedThe visitor blocked the microphone.
voice.errorThe call failed.message
chat.session-startedA chat has started.sessionId (not sent for ElevenLabs chats)
chat.messageA message was sent or received.role (user or assistant), content
chat.agent-typing-started, chat.agent-typing-stoppedThe agent starts and stops writing a reply.
chat.session-endedThe chat has ended.reason, for example user, inactivity or hidden-tab (the visitor left the page or, on some engines, switched tabs)
chat.errorA chat request failed.message

Every voice.* and chat.* event also includes provider, the engine the widget runs on.

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() and acceptConsent() 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 call window.VoiceAIWidget.init('container-id', { id: 'YOUR_WIDGET_ID', host: 'https://YOUR_DOMAIN', hideLauncher: true }). It returns an object with the same methods plus destroy(). With this method, events are sent on the container element.
  • Page variables (VAW Native). Pass details about the visitor with the variables attribute, or the variables option of init. 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

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.

Check that:

  • You waited for widget.ready before 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.error to see the reason.
  • Consent isn't waiting. If you get widget.consent-required, show your notice and call acceptConsent().
  • No call is already running. The browser console shows "VoiceAIWidget: a call is already active" if one is.

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.