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

# Widget web

> Integra tu asistente como un widget de voz y chat en cualquier sitio web

El widget web coloca a tu asistente en tu sitio web: los visitantes hacen clic en un botón y **hablan con el asistente en el navegador** (WebRTC, sin teléfono, sin app) o escriben en un **chat** con el mismo cerebro del asistente. La disponibilidad depende del plan (`web_widget`).

## Voz + chat, un solo asistente

* **Voz** — un clic inicia una conversación de voz en vivo usando la configuración completa del asistente: modo de motor, voz, base de conocimientos, herramientas, barreras de seguridad. Las llamadas web aparecen en tu historial de llamadas con la dirección `web`.
* **Chat** — el mismo asistente, prompts y base de conocimientos en formato texto, para los visitantes que no pueden o no quieren hablar.

Como ambos canales comparten una sola configuración de asistente, mantienes el comportamiento en un solo lugar.

## Insertar el widget

Crea un widget en **Ajustes → Canales → Widget web** y elige **Visualización**:

* **Flotante** (predeterminado) — burbuja en la esquina; Posición y Estado inicial aplican. Prefiere el cargador script (`allow="microphone"`):

```html theme={null}
<script
  src="https://YOUR-DOMAIN/widget.js"
  data-famulor-key="wgt_YOUR_PUBLIC_KEY"
  async
></script>
```

* **Inline** — widget en el flujo de la página (sin launcher). Prefiere web component o iframe:

```html theme={null}
<famulor-widget
  data-key="wgt_YOUR_PUBLIC_KEY"
  style="display:block;width:100%;max-width:360px;aspect-ratio:9/16;border-radius:20px;overflow:hidden;"
></famulor-widget>
<script src="https://YOUR-DOMAIN/widget.js" async></script>
```

O script con contenedor: `data-famulor-target="#famulor-assistant"`. El panel de incrustación incluye fragmentos HTML, React y Markdown.

## Orígenes permitidos

Lista el o los sitios que pueden incrustar el widget (orígenes exactos como `https://example.com`, o comodines de subdominio como `*.example.com`). Localhost está admitido para desarrollo. Los orígenes son **opcionales** al crear o guardar.

* Una lista vacía **no** significa «abierto a cualquier sitio»: se bloquean orígenes externos. Solo el dominio de la plataforma sigue permitido para que la vista previa en la app funcione.
* Añade cada host de producción (y staging) que cargará el fragmento antes de publicar. Si el widget no carga en un sitio de cliente, revisa primero Allowed origins.

## Personalización

* **Visualización** — **Flotante** (launcher en esquina) o **Inline** (incrustado en el flujo). Posición y Estado inicial solo aplican a Flotante.
* **Colores y marca** — color del botón, acento del panel, logo; la marca del tenant se aplica automáticamente en los dominios de marca blanca.
* **Posición** — esquina del launcher flotante (oculto en Inline).
* **Modos** — solo voz, solo chat, o ambos.
* **Presencia de voz** — visualizador de audio clásico o un **avatar de IA virtual** (ver abajo).
* **Textos** — etiqueta del botón, mensaje de bienvenida, aviso de IA, aviso de privacidad.
* **Formulario previo al chat** — formulario opcional antes de que empiece el chat o la voz (ver abajo).

## Avatar de IA virtual

Función separada condicionada al plan (`ai_avatar`). En el editor del widget, elige **AI avatar** en presencia de voz y selecciona un avatar.

* **Diseños**
  * **Avatar only (full-bleed)** — tarjeta compacta centrada en el rostro (estilo Anam). Flotante: **Expandido** o **Minimizado**; Inline muestra la tarjeta en el layout.
  * **Avatar + chat** — presencia de avatar con el panel clásico de chat/voz.
* **Facturación** — los minutos de voz con avatar cobran la tarifa normal de minuto de conversación **más un recargo de avatar** (actualmente **+80 créditos/min**). Consulta [Cómo se facturan los minutos](/billing/minutes) y Usage en la app.
* Sin `ai_avatar` en el plan, el editor muestra una puerta de actualización y la API rechaza activar la presencia de avatar.

## Formulario previo al chat

En **Widgets →** abre un conector → activa **Formulario previo al chat**. Los visitantes completan campos antes de que empiece la sesión.

* **Las sugerencias** provienen de los campos de contacto (nombre, correo electrónico, teléfono), las variables de entrada del asistente seleccionado y los atributos de Audience del espacio de trabajo. También puedes agregar claves personalizadas.
* Los valores enviados se convierten en **variables de entrada** de la llamada (`{{variable_key}}`), actualizan el lead de Audience cuando hay campos de identidad presentes, y aparecen en **Historial** dentro de Formulario previo al chat / Variables de entrada.
* La configuración se guarda en el conector del widget (`theme.preform`) y se expone en la configuración pública del widget; el endpoint del token valida los campos obligatorios.

## Antes de publicar, revisa esto

<Steps>
  <Step title="Añade al menos un origen permitido">
    Lista cada sitio que incrustará el widget. Sin orígenes, los hosts de terceros no pueden cargar la configuración ni emitir tokens.
  </Step>

  <Step title="Primero prueba el asistente con llamadas desde el navegador">
    El widget usa la misma ruta de llamada web que la llamada de prueba del editor de asistentes — si esa funciona bien, el widget también funcionará.
  </Step>

  <Step title="Ten en cuenta los permisos de micrófono">
    Los navegadores exigen HTTPS para acceder al micrófono. La página anfitriona no debe bloquear el micrófono con `Permissions-Policy`. Los embeds script / web component configuran `allow="microphone"` en el iframe automáticamente.
  </Step>

  <Step title="Actualiza tu política de privacidad">
    Las conversaciones de voz se procesan como llamadas (transcripciones, grabación opcional con flujo de consentimiento). Menciona el widget en tu política de privacidad.
  </Step>
</Steps>

## API & MCP

Gestiona widgets con la API REST pública (`/api/v1/widget-connectors`) y las herramientas MCP (`create_widget_connector`, `update_widget_connector`, …). `allowed_origins` es opcional (vacío/omitido bloquea hosts de terceros). Ámbito: `assistants:write`. Plan: `web_widget` (presencia de avatar también necesita `ai_avatar`).