Widget de voz - Lovi AI Documentation

El widget de voz es una cápsula flotante. El visitante inicia una llamada hablada en el navegador: el iframe de Lovi pide el micrófono y el Agente responde en audio. No lo confundas con:

El widget web de chat (burbuja de texto; el mismo script sin mode="voice").
Las llamadas telefónicas a Twilio o Ringover.
Las campañas de voz (POST /functions/v1/notify/voice).

El embed de producción es https://widget.lovi.ai/iawidget.js con mode="voice". El repo voice-widget-lovi es un prototipo (sin iframe de Lovi). No lo copies.

Cómo integrarlo

Pégalo antes de </body>. mode="voice" carga voz en lugar del chat:

<script
  customer="TU_ACCESS_KEY"
  widget="TU_WIDGET_ID"
  mode="voice"
  src="https://widget.lovi.ai/iawidget.js"
  defer
></script>

Atributo	Requerido	Qué es
`src`	Sí	`https://widget.lovi.ai/iawidget.js`
`customer`	Sí	Access key de la compañía (el script la manda como `access_key`). No es el UUID del widget.
`widget`	Sí	UUID del widget.
`mode`	Sí	Debe ser `voice`. Sin él, el mismo script carga chat de texto.
`language-lovi`	No	Idioma. Si falta, `navigator.language` (dos letras). No uses `language="en"`.

Orden del loader: primero mode="voice", luego WhatsApp full, luego chat. Si hay voz y WhatsApp full, carga voz. No hay dom para voz: el iframe es position:fixed; bottom:0. El dom del chat no aplica. No hay npm ni window.startVoice. El visitante pulsa la cápsula.

Qué ve el visitante

Aparece el control (esquina, fijo).
Con un clic real, el navegador pide el micrófono (getUserMedia dentro del iframe de Lovi).
Oye al agente y puede colgar.
Tras colgar, feedback 👍/👎.

Prueba en HTTPS o localhost. Si tu página mete el widget en un iframe de otro origen, ese iframe necesita allow="microphone" y, si usas Permissions-Policy, permitir microphone hacia https://widget.lovi.ai. El iframe de Lovi ya lleva allow="microphone; autoplay".

Aspecto

Colores, posición y animación salen de GET /functions/v1/voice-widget (Voice-config). En el HTML solo fuerzas idioma con language-lovi.

Audio y paso a humano (lo hace el iframe)

No llames estos endpoints desde tu página. El iframe:

GET …/functions/v1/voice-widget — solo apariencia (Voice-config). No es la sesión de audio.
GET …/functions/v1/voice-widget/signed-url — sesión ElevenLabs ConvAI (URL firmada + SDK).
También usa: POST …/voice-widget/search, feedback, POST …/voice-widget/handoff, POST …/voice-widget/handoff/end, GET …/voice-widget/chat-by-conversation.

Sí hay transferencia a humano en el iframe de voz (transferring / waiting_agent / with_human, LiveKit). No es una API pública para el JavaScript de tu web.

Requisitos técnicos (página anfitriona)

La página debe poder llamar al menos a:

https://widget.lovi.ai
https://cloud.lovi.ai
https://api.elevenlabs.io y wss://api.elevenlabs.io
wss://livekit.rtc.elevenlabs.io
https://cloud-api.livekit.io
https://cdn.jsdelivr.net

Ni iawidget.js ni widget.lovi.ai envían Content-Security-Policy. Esta lista es para tu CSP / firewall.

Resolución de problemas

Problema	Qué revisar
No aparece nada	`iawidget.js` 200. Bloqueadores.
`LOVI ERROR (voz): customer/widget no definidos`	Faltan atributos. `customer` es la access key.
Sale el chat	Falta `mode="voice"`.
El micrófono no arranca	HTTPS/`localhost`, clic real, permiso, `allow="microphone"` en tu iframe, Permissions-Policy a `widget.lovi.ai`.
Script / audio / WebRTC bloqueados	Allowlist de los hosts de arriba, incluidos `wss:` LiveKit y ElevenLabs.

Relacionado

Configuración del Widget Web — chat (sin mode).
Números de Teléfono e IA de Voz
API del widget de voz
API de notificaciones de voz

​Cómo integrarlo

​Qué ve el visitante

​Aspecto

​Audio y paso a humano (lo hace el iframe)

​Requisitos técnicos (página anfitriona)

​Resolución de problemas

​Relacionado