> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget de voz

> Integra una llamada de voz con tu Agente de IA en tu sitio web. El visitante pulsa el botón de voz, autoriza el micrófono y habla en el navegador.

El **widget de voz** es una cápsula flotante en tu web. El visitante inicia una **llamada hablada** en el navegador: el sitio pide el micrófono y el Agente de IA responde en audio.

No lo confundas con:

* El [widget web de chat](./ug_webwidget_es) (burbuja de mensajes de texto).
* Las [llamadas telefónicas](./voice-config) a un número Twilio o Ringover.
* Las [campañas de voz](/es/api-reference/voice_notifications) (`POST /functions/v1/notify/voice`).

En este flujo el visitante habla con la IA en la página. No hay transferencia a un agente humano desde la cápsula.

## Cómo integrarlo

Pégalo antes de `</body>` en las páginas donde quieras la cápsula (o en el `index.html` principal para todo el sitio). `mode="voice"` es lo que carga voz en lugar del chat de texto:

```html theme={null}
<script
  customer="TU_COMPANY_ID"
  widget="TU_WIDGET_ID"
  mode="voice"
  src="https://widget.lovi.ai/iawidget.js"
  defer
></script>
```

| Atributo                            | Requerido | Qué es                                                                                          |
| ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------- |
| `customer`                          | Sí        | ID de tu compañía.                                                                              |
| `widget`                            | Sí        | ID del widget.                                                                                  |
| `mode`                              | Sí        | Debe ser `voice`. Sin este atributo, el mismo script carga el chat de texto.                    |
| `src`                               | Sí        | `https://widget.lovi.ai/iawidget.js`                                                            |
| `language-lovi`                     | No        | Código de idioma (`es`, `en`, …). Si falta, se usa el idioma del navegador.                     |
| `dom`                               | No        | Selector de un nodo si incrustas el iframe en un elemento de la página.                         |
| `whatsapp_type` / `whatsapp_number` | No        | Si `whatsapp_type` es `full` y hay número, se abre WhatsApp y **no** se carga el widget de voz. |

Copia `customer` y `widget` desde la configuración del widget en Lovi (el mismo criterio que el script del chat). No hay paquete npm ni métodos JavaScript públicos (`window.startVoice`, etc.): el visitante pulsa la cápsula.

## Qué ve el visitante

1. Aparece el control de voz en la página.
2. Al pulsar (tiene que ser un clic real: el audio no arranca solo), el navegador pide el micrófono.
3. Durante la llamada oye al agente y puede colgar.
4. Tras colgar puede dejar un feedback 👍/👎. La cápsula vuelve al estado inicial.

Prueba en **HTTPS** o en `localhost`. El micrófono no funciona en HTTP plano.

## Aspecto

Colores, posición, animación de la conversación, imagen de fondo y CSS extra los aplica Lovi al cargar el widget. No se configuran en el HTML, salvo `language-lovi` y `dom`.

## Requisitos técnicos

* Navegadores actuales (no Internet Explorer 11).
* Permiso de micrófono.
* El audio arranca en el clic del usuario (política de autoplay del navegador).
* La página debe poder llamar a `https://widget.lovi.ai`, `https://cloud.lovi.ai` y `https://api.elevenlabs.io`.

## Resolución de problemas

| Problema                                                  | Qué revisar                                                                                                                                                    |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No aparece nada                                           | ¿Cargó el script? En DevTools → Red, `iawidget.js` debe devolver 200. Bloqueadores y extensiones de privacidad lo cortan a menudo: prueba una ventana privada. |
| Consola: `LOVI ERROR (voz): customer/widget no definidos` | Faltan `customer` o `widget`. Cópialos de la configuración del widget en Lovi.                                                                                 |
| Sale el chat de texto, no la voz                          | Falta `mode="voice"`. Sin ese atributo, el mismo script carga el chat.                                                                                         |
| El micrófono no arranca                                   | La página debe ser **HTTPS** o `localhost`. Permite el micrófono en el navegador (candado de la barra). El audio solo arranca tras un clic real.               |
| El widget va dentro de *tu* iframe                        | Un iframe de otro origen bloquea el micrófono si no tiene `allow="microphone"`. El iframe que crea Lovi ya lleva `allow="microphone; autoplay"`.               |
| Script o audio bloqueados                                 | Incluye en la CSP, firewall o tag manager: `widget.lovi.ai`, `cloud.lovi.ai` y `api.elevenlabs.io`.                                                            |

## Relacionado

* [Configuración del Widget Web](./ug_webwidget_es) — chat de texto.
* [Números de Teléfono e IA de Voz](./voice-config) — llamadas al número de la empresa.
* [API del widget de voz](/es/api-reference/voice_widget) — cómo obtiene el script la configuración.
* [API de notificaciones de voz](/es/api-reference/voice_notifications) — campañas salientes por teléfono.