Web voice widget

The web voice widget is a button you add to any web page. A visitor opens it, starts a call, and talks to your agent through the microphone. The agent answers out loud, in real time.

Before you start

• An agent with Voice turned on
• A voice provider: Gemini, or ElevenLabs with ELEVENLABS_API_KEY in Settings
• A page served over HTTPS. Browsers only allow microphone access on secure pages (and on localhost for testing).

Turn on the widget

1. Open Agents and edit the agent.

2. In Channels, turn on Voice, then Web Voice Widget. The widget can’t be turned on while Voice is off.

3. In Voice Configuration, choose the Voice Provider and Language. Then pick a Gemini Voice, or enter the ElevenLabs Voice ID from your ElevenLabs dashboard.

4. Save the agent.

5. Open Integration URLs and copy Web Voice Widget Embed Code.

Note

Voice calls don’t use the model in AI Model Configuration. That model only applies to the text channels.

Add it to your page

Paste the code before </body>. Use your VirtuAI host in every URL, including the two scripts under /static/js/:

<!-- Voice Assistant Widget -->
<link rel="stylesheet" href="https://<your-virtuai-host>/static/voice-assistant-widget.css">
<script src="https://<your-virtuai-host>/static/js/client-tool-types.js"></script>
<script src="https://<your-virtuai-host>/static/js/client-tool-renderers.js"></script>
<script src="https://<your-virtuai-host>/static/voice-assistant-widget.js"></script>
<voice-assistant
  agent-id="<agent-id>"
  base-url="https://<your-virtuai-host>"
  title="Voice Assistant"
  theme="default"
  position="bottom-right"
  color="#3b82f6">
</voice-assistant>

The two client-tool scripts let the widget show rich results, such as lists and tables, next to the spoken answer. The widget still works without them.

Caution

Keep base-url. Without it, the widget tries to connect to your own site instead of VirtuAI.

Options

Attribute	Default	What it does
agent-id	—	The agent to talk to. Required.
base-url	The page’s own origin	Your VirtuAI address. Set it on any site that isn’t VirtuAI.
title	Voice Assistant	Text in the widget header
theme	default	default, dark or minimal
position	bottom-right	bottom-right, bottom-left, top-right or top-left
color	#3b82f6	Main color of the button and controls
auto-open	false	Set to true to open the panel when the page loads

To match your brand more closely, override the widget’s CSS variables:

<style>
  voice-assistant {
    --voice-assistant-primary-color: #0f766e;
    --voice-assistant-background: #ffffff;
    --voice-assistant-text-primary: #1f2937;
    --voice-assistant-font-family: 'Inter', sans-serif;
    --voice-assistant-border-radius: 12px;
  }
</style>

Control it from JavaScript

The widget has four methods: open(), close(), startConversation() and endConversation(). It also sends four events: widget-opened, widget-closed, call-started and call-ended. The call events carry agentId and sessionId in event.detail.

HTML

<button id="talk">Talk to us</button>
<script>
  const widget = document.querySelector('voice-assistant');
  document.getElementById('talk').addEventListener('click', () => {
    widget.open();
    widget.startConversation();
  });
  widget.addEventListener('call-ended', (e) => {
    console.log('Call ended', e.detail.sessionId);
  });
</script>

React

import { useEffect, useRef } from 'react';

export function VoiceWidget({ agentId }) {
  const ref = useRef(null);

  useEffect(() => {
    const onStart = (e) => console.log('Call started', e.detail);
    const el = ref.current;
    el.addEventListener('call-started', onStart);
    return () => el.removeEventListener('call-started', onStart);
  }, []);

  return (
    <voice-assistant
      ref={ref}
      agent-id={agentId}
      base-url="https://<your-virtuai-host>"
    />
  );
}

Access and security

Caution

Anyone who can open the page can start a call with the agent. Only put the widget on an agent whose tools and knowledge are safe for your page’s visitors.

• The widget doesn’t send an integration key. If Key Enforcement is on under Integrations for the workspace, the widget can’t connect. See Integration keys.
• Every call uses your voice provider account.

Troubleshooting

The button doesn’t appear : Check that the CSS and JS files load from your VirtuAI host, and that the <voice-assistant> tag is on the page.

“Connection failed” : Check base-url, the agent ID, and that Voice and Web Voice Widget are on. If integration key enforcement is on in the workspace, the widget is rejected.

The browser never asks for the microphone : The page isn’t served over HTTPS, or the visitor blocked the microphone for your site in the browser settings.