Widget de voz web

El widget de voz web es un botón que agregas a cualquier página web. Un visitante lo abre, inicia una llamada y habla con tu agente a través del micrófono. El agente responde en voz alta, en tiempo real.

Antes de comenzar

• Un agente con Voice activado
• Un proveedor de voz: Gemini, o ElevenLabs con ELEVENLABS_API_KEY en Settings
• Una página que se entregue mediante HTTPS. Los navegadores solo permiten el acceso al micrófono en páginas seguras (y en localhost para pruebas).

Activa el widget

1. Abre Agents y edita el agente.

2. En Channels, activa Voice y, luego, Web Voice Widget. El widget no se puede activar mientras Voice esté desactivado.

3. En Voice Configuration, elige el Voice Provider y el Language. Luego, elige una Gemini Voice o ingresa el ElevenLabs Voice ID que aparece en tu panel de ElevenLabs.

4. Guarda el agente.

5. Abre Integration URLs y copia Web Voice Widget Embed Code.

Nota

Las llamadas de voz no usan el modelo de AI Model Configuration. Ese modelo solo se aplica a los canales de texto.

Agrégalo a tu página

Pega el código antes de </body>. Usa tu host de VirtuAI en todas las URLs, incluidas las de los dos scripts de /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>

Los dos scripts client-tool permiten que el widget muestre resultados enriquecidos, como listas y tablas, junto a la respuesta hablada. El widget funciona igual sin ellos.

Precaución

Conserva base-url. Sin este atributo, el widget intenta conectarse a tu propio sitio en lugar de a VirtuAI.

Opciones

Atributo	Valor predeterminado	Qué hace
agent-id	—	El agente con el que se habla. Obligatorio.
base-url	El origen de la propia página	Tu dirección de VirtuAI. Configúralo en cualquier sitio que no sea VirtuAI.
title	Voice Assistant	El texto del encabezado del widget
theme	default	default, dark o minimal
position	bottom-right	bottom-right, bottom-left, top-right o top-left
color	#3b82f6	El color principal del botón y los controles
auto-open	false	Configúralo como true para abrir el panel cuando se cargue la página

Para adaptarlo mejor a tu marca, anula las variables de CSS del widget:

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

Contrólalo desde JavaScript

El widget tiene cuatro métodos: open(), close(), startConversation() y endConversation(). También emite cuatro eventos: widget-opened, widget-closed, call-started y call-ended. Los eventos de llamada incluyen agentId y sessionId en 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>"
    />
  );
}

Acceso y seguridad

Precaución

Cualquier persona que pueda abrir la página puede iniciar una llamada con el agente. Coloca el widget solo en un agente cuyas herramientas y conocimiento sean seguros para los visitantes de tu página.

• El widget no envía una clave de integración. Si Key Enforcement está activado en Integrations para el espacio de trabajo, el widget no puede conectarse. Consulta Claves de integración.
• Cada llamada usa tu cuenta del proveedor de voz.

Solución de problemas

El botón no aparece : Verifica que los archivos CSS y JS se carguen desde tu host de VirtuAI y que la etiqueta <voice-assistant> esté en la página.

“Connection failed” : Verifica base-url, el ID del agente y que Voice y Web Voice Widget estén activados. Si la aplicación obligatoria de claves de integración está activada en el espacio de trabajo, el widget se rechaza.

El navegador nunca pide acceso al micrófono : La página no se entrega mediante HTTPS, o el visitante bloqueó el micrófono para tu sitio en la configuración del navegador.