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

# Widget web

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

El widget web pone tu asistente en tu sitio web: los visitantes hacen clic en un botón y **hablan con el asistente en el navegador** (sin necesidad de teléfono ni app) o escriben en un **chat** con el mismo asistente. El widget está disponible cuando está incluido en tu plan.

## Voz + chat, un solo asistente

* **Voice** — un clic inicia una conversación de voz en directo con la configuración completa del asistente: modo de motor, voz, base de conocimientos, herramientas, barreras de seguridad. Las llamadas web aparecen en [History](/es/monitoring/history) con dirección `web`.
* **Chat** — el mismo asistente, los mismos prompts y la misma base de conocimientos en forma de texto, para quienes no pueden o no quieren hablar.

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

## Incrustación

Crea un widget en **Settings → Channels → Web Widget**, y luego pega un fragmento de código del editor. Elige **Display**:

<Tabs>
  <Tab title="Floating">
    El valor predeterminado — una burbuja de lanzador en una esquina. Se aplican Position e Initial state. Prioriza el cargador de **script** (configura `allow="microphone"` en el iframe automáticamente):

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

  <Tab title="Inline">
    El widget se sitúa dentro del flujo de tu página (sin lanzador). Prioriza el componente web o el fragmento de iframe (incluye dimensionado vertical para las tarjetas de avatar):

    ```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 móntalo en un nodo de destino: `data-famulor-target="#famulor-assistant"` en la etiqueta script.
  </Tab>
</Tabs>

Consulta el panel de incrustación para ver fragmentos ya preparados en HTML, React y Markdown. En dominios de marca blanca, el widget se sirve desde **el dominio de tu tenant** con tu marca.

## Orígenes permitidos

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

* Una lista vacía **no** significa "abierto a cualquier sitio": los orígenes externos quedan bloqueados. Solo el propio dominio de la plataforma permanece permitido, para que la vista previa en directo dentro de la app siga funcionando.
* Añade cada host de sitio web que vaya a cargar el fragmento antes de publicarlo. Si el widget no carga en el sitio de un cliente, revisa primero Allowed origins.

## Personalización

* **Display** — **Floating** (lanzador en una esquina) o **Inline** (incrustación en la página). Position e Initial state solo se aplican a Floating.
* **Colors and branding** — color del lanzador, acento del panel, logotipo; la marca del tenant se aplica automáticamente en dominios de marca blanca.
* **Position** — la esquina donde se coloca el lanzador flotante (oculto para Inline).
* **Modes** — solo voz, solo chat, o ambos.
* **Voice presence** — visualizador de audio clásico, o un **virtual AI avatar** (ver más abajo).
* **Launcher icon** — Milian, Chat bubbles, Question mark, Smiley face, Team o Hand wave. Se aplica a solo chat, solo voz y ambos.
* **Launcher label** — preajustes (**No text** por defecto; Help, Ask anything, Assistance, Support, Live Chat, Need help?) traducidos según el idioma del navegador del visitante. El modo solo avatar sigue usando un texto de lanzador personalizado opcional para el CTA glass.
* **Texts** — mensaje de bienvenida, aviso de IA, aviso de privacidad.
* **Pre-chat form** — formulario opcional antes de iniciar el chat o la voz (ver más abajo).

## Avatar de IA virtual

Los avatares virtuales requieren la función AI Avatar. En el editor del widget, configura **Voice presence** como **AI avatar** y elige un avatar.

* **Layouts**
  * **Avatar only (full-bleed)** — tarjeta compacta centrada en el rostro. Los widgets Floating pueden iniciar **Expanded** o **Minimized**; Inline siempre muestra la tarjeta en su sitio.
  * **Avatar + chat** — presencia del avatar junto con el marco clásico del panel de chat/voz.
* **Billing** — las sesiones de voz se facturan a la tarifa normal por minuto de conversación, más el recargo **Web widget virtual avatar** por minuto mientras un avatar virtual esté activo; los mensajes de chat de texto simple enviados y recibidos facturan créditos por mensaje a la tarifa **Web chat (sent)** / **Web chat (received)** del espacio de trabajo. Las tarifas actuales están en la [página Usage](https://app.famulor.io/usage); consulta también [Cómo se facturan los minutos](/es/billing/minutes).
* Sin acceso a AI Avatar, el editor muestra una opción de mejora de plan y la API rechaza activar la presencia de avatar.

## Formulario previo al chat

Abre el widget en el editor, busca **Pre-chat form** y activa **Enable**. Los visitantes rellenan entonces los campos antes de que empiece la sesión.

* Las **Suggestions** proceden 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 añadir claves personalizadas.
* Los valores enviados se convierten en **input variables** de la llamada (`{{variable_key}}`), actualizan el lead de Audience cuando hay campos de identidad presentes, y aparecen en **History** bajo Pre-chat form / Input variables.
* Los campos obligatorios se validan antes de que un visitante pueda iniciar una sesión.

## Antes de publicar el widget

<Steps>
  <Step title="Añade al menos un origen permitido">
    Indica cada sitio que vaya a incrustar el widget. Sin orígenes, los hosts externos no pueden cargar la configuración ni generar tokens.
  </Step>

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

  <Step title="Ten en cuenta los permisos del micrófono">
    Los navegadores exigen HTTPS para acceder al micrófono. La página anfitriona no debe bloquear el micrófono mediante `Permissions-Policy`. Las incrustaciones por script o componente web 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>

## Solución de problemas

<AccordionGroup>
  <Accordion title="El widget no aparece en absoluto">
    Confirma que el fragmento de incrustación está antes de la etiqueta de cierre `</body>`, haz una recarga forzada (o pruébalo en una ventana privada) para descartar HTML en caché, comprueba que tu plan incluye el widget web y busca errores de JavaScript en la consola del navegador. Copia el fragmento de nuevo desde el editor del widget si has cambiado la clave del conector desde entonces.
  </Accordion>

  <Accordion title="El widget carga en otros sitios pero no en este">
    Revisa primero **Allowed origins**. Una lista vacía bloquea por diseño cualquier host externo; añade el origen exacto (o un comodín `*.example.com`) en el que está incrustado el widget.
  </Accordion>

  <Accordion title="La voz no se inicia">
    La voz requiere HTTPS. Confirma que la página se sirve por HTTPS, que el navegador ha concedido permiso de micrófono, que el micrófono funciona en otras apps y que ninguna VPN ni firewall está bloqueando WebRTC. Las incrustaciones por script y componente web configuran `allow="microphone"` automáticamente — una incrustación de iframe sin procesar necesita añadir ese atributo manualmente.
  </Accordion>

  <Accordion title="El chat no responde">
    Busca errores en la consola del navegador, confirma que el asistente funciona desde una llamada o chat de prueba en el editor del asistente, y recarga la página para iniciar una sesión de widget nueva.
  </Accordion>

  <Accordion title="Las respuestas del Pre-chat form no llegan al asistente">
    Las respuestas llegan bajo la clave de cada campo, así que elige la sugerencia (o define la clave personalizada) que coincida con la variable que lee tu asistente, y guarda el widget antes de volver a probar.
  </Accordion>

  <Accordion title="Los cambios en el editor no se reflejan">
    Asegúrate de haber guardado los ajustes del widget, y luego haz una recarga forzada o pruébalo en una ventana privada; un fragmento de incrustación antiguo en caché también puede ocultar un cambio de configuración reciente.
  </Accordion>

  <Accordion title="Incrustación en WordPress u otro CMS">
    Usa un bloque de HTML personalizado, mantén el fragmento antes de la etiqueta de cierre `</body>`, y borra la caché de cualquier plugin de caché después de guardar. Los plugins de seguridad o firewall a veces bloquean el script del widget — desactívalos de uno en uno para aislar la causa.
  </Accordion>
</AccordionGroup>

¿Sigues atascado? Pruébalo en una ventana de incógnito y en un segundo navegador para descartar extensiones y estado en caché, y después contacta con soporte con una captura de pantalla y la salida de la consola del navegador.

## API & MCP

Gestiona widgets mediante programación con la API REST pública (`/api/v1/widget-connectors`) y las herramientas MCP (`create_widget_connector`, `update_widget_connector`, …). `allowed_origins` es opcional; si está vacío u omitido, bloquea los hosts externos. Scope: `assistants:write`. El acceso al widget y a AI Avatar depende de tu plan.

Los widgets nuevos reutilizan inicialmente el retrato del asistente seleccionado como logotipo de cabecera, cuando está disponible. Puedes reemplazarlo o eliminarlo más tarde.