Widget de voz para sitios web

Qué lograrás

Añadirás un botón flotante a tu propio sitio web. Un visitante lo pulsa, permite su micrófono y habla con el mismo agente que pruebas en el panel: las mismas instrucciones, voz, conocimiento y herramientas. No hay una segunda copia del agente que mantener al día.

Requisitos previos

• Un agente publicado. Un agente sin publicar no muestra nada a los visitantes.
• Crédito en tu espacio de trabajo, o minutos gratuitos disponibles en el plan Free. Consulta Cómo afecta a tu crédito más abajo.
• Un sitio web donde puedas añadir una línea de código, servido por https. Los navegadores solo permiten el micrófono en páginas seguras.

Actívalo

1. Abre el agente, elige la pestaña Website y luego la tarjeta Voice Widget. (La otra tarjeta, Website Form, es el formulario de devolución de llamada: consulta Formulario de devolución de llamada para sitios web.)
2. En la pestaña Configuration, bajo Website, escribe la dirección de tu sitio web (por ejemplo example.com) y pulsa Enter o Add. Repítelo para cada sitio web que mostrará el widget. Cada uno aparece como una fila de la lista, y la × de una fila la elimina.
3. Activa Show the widget on my website.
4. Espera a que aparezca Widget settings saved arriba a la derecha de Live Preview.

No hay botón de guardar. Cada cambio se guarda automáticamente un instante después de que dejas de escribir. Si algo todavía no se puede guardar (por ejemplo, el interruptor está activado pero no hay ningún sitio en la lista), un aviso que puedes cerrar, en la parte superior de los ajustes, dice el motivo. La esquina muestra Saving con puntos en movimiento y luego Widget settings saved. En cuanto un cambio se guarda con el interruptor activado, el widget queda activo para los visitantes.

Para detenerlo más adelante, desactiva el interruptor y espera a Widget settings saved. Las llamadas nuevas se rechazan de inmediato y el botón desaparece de las páginas en unos minutos (los navegadores conservan la configuración hasta 30 segundos y el script hasta cinco minutos). Una llamada que ya está en curso no se corta.

Los miembros de tu espacio de trabajo pueden ver la pestaña, pero solo un propietario o administrador puede cambiarla.

Elige su aspecto

Abre la pestaña Appearance para el icono, la posición y los colores. Los textos (título, etiqueta del botón, saludo y enlace de privacidad) están en la pestaña Configuration, debajo de Website.

• Icon: teléfono, micrófono o chat.
• Button colour e Icon colour: el botón redondo y el icono que lleva.
• Panel colour: el fondo del panel emergente. El texto, los bordes y los tonos suaves de dentro se ajustan solos, así que un panel oscuro lleva texto claro. Phynxa guarda los colores que elijas tal cual, así que revisa la vista previa para comprobar que el icono y el botón se ven bien.
• Position: abajo a la derecha o abajo a la izquierda.
• Widget title y Button label: el título del panel y el texto del botón que inicia la llamada.
• Greeting message: se muestra en el panel antes de empezar la llamada. Lo que el agente dice en voz alta es su propia frase inicial, que se define en la pestaña Assistant.
• Privacy policy link (opcional): una dirección https que se muestra bajo el panel.

La Live Preview junto a los ajustes es el widget real, dibujado sobre una página de ejemplo. No se pueden iniciar llamadas desde la vista previa.

Elige los sitios web permitidos

El widget funciona solo en los sitios web que enumeras. Una página de cualquier otro sitio que tenga tu código no obtiene nada. Puedes pegar varias direcciones a la vez en el cuadro, separadas por espacios o comas.

Reglas importantes:

• Los subdominios nunca se aceptan salvo que escribas la línea con *.. Si quieres el dominio sin subdominio y sus subdominios, añade las dos líneas.
• Solo funcionan los sitios https. http se rechaza.
• Las direcciones se normalizan al guardar: se quitan las mayúsculas, el https:// inicial y cualquier ruta.
• Se rechazan las direcciones IP y las líneas *. que cubrirían todo un dominio público, como *.com o *.co.uk.
• Puedes enumerar hasta 20 sitios web.
• Para probar en tu propio ordenador, quien administra tu servidor de Phynxa puede permitir localhost (consulta Para quien administra el servidor). Está desactivado por defecto.

Qué puede y qué no puede hacer la comprobación del sitio

Los navegadores le dicen al servidor de qué sitio web procede una solicitud, y una página de otro sitio no puede cambiarlo. Por eso tu widget no puede ser "prestado" por el sitio de otra persona. Un programa que no sea un navegador puede afirmar ser cualquier sitio, así que la lista no es un cerrojo frente a alguien decidido. Lo que lo limita es todo lo demás: cada dirección y cada widget solo pueden iniciar cierto número de llamadas por minuto, solo pueden estar abiertas unas pocas a la vez, las llamadas son más cortas que las telefónicas y cada llamada necesita que se reserve crédito antes. Si ves llamadas que no reconoces, apaga el widget y escribe a soporte.

Instala el widget en tu sitio web

Instalar significa pegar un fragmento corto de código en tu sitio web. Sigue los cuatro pasos en orden.

Paso 1. Obtén tu código

1. En Phynxa, abre Voice agents, elige tu agente y abre la pestaña Website.
2. Comprueba que tu sitio web figura en la pestaña Configuration y que el interruptor está activado (consulta Actívalo arriba).
3. Abre la pestaña Embed Code y pulsa Copy.

El código se ve así, con tu propio ID de widget. Contiene solo tu ID público de widget. No hay claves ni contraseñas, y el ID por sí solo no permite hacer ninguna llamada: cada llamada se comprueba con tu lista de sitios web y tu interruptor.

<script
  src="https://your-phynxa-address/widget.js"
  data-widget-id="wgt_..."
  async
></script>

Paso 2. Pégalo en tu sitio web

Busca abajo tu tipo de sitio web y sigue sus pasos. En todos los casos el código va en cada página donde quieras el botón, y el mejor lugar es justo antes de la etiqueta de cierre </body> (el pie de página, o "final del body").

Un sitio hecho de archivos (HTML simple)

1. Abre el archivo de tu página, por ejemplo index.html, en un editor de texto. Si todas tus páginas comparten una plantilla o un archivo de pie de página, abre ese, para que el botón aparezca en todas.
2. Busca la línea con </body> cerca del final.
3. Pega el código en la línea justo encima.
4. Guarda el archivo y súbelo a tu alojamiento web (con FTP, el administrador de archivos de tu proveedor o como publiques normalmente).

Next.js

1. Abre app/layout.tsx (App Router). Con el Pages Router, abre pages/_app.tsx.
2. Arriba, añade import Script from "next/script";.
3. Dentro de <body>, después de {children}, añade el Script de abajo, con tu propia dirección e ID. En pages/_app.tsx, ponlo después de <Component {...pageProps} />.
4. Guarda y despliega como siempre.

import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://your-phynxa-address/widget.js"
          data-widget-id="wgt_..."
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

React (Vite o Create React App)

1. Lo más fácil: abre index.html (en la carpeta del proyecto con Vite, en la carpeta public con Create React App) y pega el código del Paso 1 justo antes de </body>.
2. Vuelve a compilar y despliega tu sitio.

Si prefieres añadirlo en código, pon este componente una sola vez en tu componente principal (App.tsx):

import { useEffect } from "react";

export function VoiceWidget() {
  useEffect(() => {
    const script = document.createElement("script");
    script.src = "https://your-phynxa-address/widget.js";
    script.dataset.widgetId = "wgt_...";
    script.async = true;
    document.body.appendChild(script);
    return () => script.remove();
  }, []);
  return null;
}

WordPress

1. En el administrador de WordPress, ve a Plugins, Añadir nuevo plugin.
2. Busca WPCode (WPCode Insert Headers and Footers), instálalo y actívalo.
3. Ve a Code Snippets, Header & Footer.
4. Pega el código en el cuadro Footer y pulsa Save Changes.

Shopify

1. En el administrador de Shopify, ve a Online Store, Themes.
2. Junto a tu tema activo, pulsa ... y elige Edit code.
3. Abre layout/theme.liquid.
4. Pega el código en la línea justo encima de </body> y pulsa Save.

Wix

1. En el panel de tu sitio, ve a Settings, Custom Code (requiere un plan de pago con dominio conectado).
2. Pulsa Add Custom Code y pega el código. Ponle el nombre "Phynxa voice widget".
3. En Add Code to Pages, elige All pages. En Place Code in, elige Body - end.
4. Pulsa Apply y publica tu sitio.

Squarespace

1. Ve a Settings, Developer Tools, Code Injection (en sitios antiguos, Settings, Advanced, Code Injection). Requiere un plan que permita la inyección de código.
2. Pega el código en el cuadro Footer.
3. Pulsa Save.

Webflow

1. Abre Site settings, Custom code (requiere un plan de sitio de pago).
2. Pega el código en el cuadro Footer code.
3. Pulsa Save y publica tu sitio.

Google Tag Manager

1. Crea una nueva Tag de tipo Custom HTML y pega el código.
2. Elige el activador All Pages.
3. Guarda, luego Submit y publica el contenedor.

Cualquier otro creador de sitios

Busca un ajuste llamado "custom code", "code injection", "header and footer" o "scripts". Elige la posición de pie de página o final del body, pega el código y guarda. Si no encuentras ninguno, envía el código del Paso 1 a quien se ocupe de tu sitio web y pídele que lo añada antes de </body> en todas las páginas.

Los nombres de los menús cambian de vez en cuando. Si alguno no coincide con lo que ves, busca las mismas palabras cerca.

Paso 3. Publica tu sitio web

Pegar el código no basta por sí solo. En la mayoría de las plataformas, un cambio solo lo ven los visitantes después de que lo publiques, lo despliegues o lo subas. Hazlo ahora. Si usas un plugin de caché o una CDN, vacía su caché.

Paso 4. Comprueba que funciona

1. Abre tu sitio web en una ventana normal del navegador, en una de las direcciones que enumeraste. Actualiza varias veces si no ves el cambio.
2. Busca el botón redondo en la esquina que elegiste.
3. Púlsalo, pulsa el botón de inicio, permite el micrófono y di hola. El agente debería responder.
4. De vuelta en Phynxa, abre la pestaña Embed Code y mira el panel Installation bajo el código: Not seen yet cambia a Installed, con la dirección del sitio. Pulsa Check again si todavía no ha cambiado. Copiar el código no cuenta: cambia solo después de que el navegador de un visitante haya cargado tu página con el código.

Si el botón no aparece, consulta Solución de problemas más abajo.

Si tu sitio web tiene una Content Security Policy

Una política estricta puede bloquear el widget. Permite tu dirección de Phynxa para scripts (script-src) y para conexiones, incluido wss: (connect-src). El widget carga su ayudante de audio desde la misma dirección como un archivo de script normal, no desde una dirección blob:.

Qué ve un visitante

1. Un pequeño botón redondo en la esquina que elegiste, con el título de tu widget en una pequeña etiqueta a su lado.
2. Al pulsarlo se abre un panel compacto con tu título, tu saludo como un globo de conversación y un botón redondo grande de inicio con el texto de tu botón debajo.
3. Al pulsar el botón de inicio se pide una llamada al servidor. Solo entonces el navegador pide el micrófono, y el panel dice Permite el acceso al micrófono mientras la ventana del propio navegador está abierta. No se graba ni se envía nada antes de que el visitante lo permita.
4. El visitante habla y oye al agente. El panel muestra si el asistente está escuchando, pensando o hablando, un cronómetro de la llamada y la última frase del agente como texto. Los botones redondos de abajo silencian el micrófono o terminan la llamada. Cerrar el panel también termina la llamada.
5. Cuando el agente termina la llamada, o se alcanza el límite de tiempo, el panel muestra Llamada terminada con un botón Cerrar. Al pulsar de nuevo el botón redondo se inicia una llamada nueva.

El panel indica que es un asistente de IA y que la conversación se transcribe. Phynxa no graba el audio de las llamadas; guarda la transcripción, que aparece en History como cualquier otra llamada. Si necesitas informar más a los visitantes, añade el enlace a tu política de privacidad.

Los textos del panel siguen el idioma del agente cuando Phynxa los tiene (inglés, español y árabe); los demás idiomas muestran inglés.

Las llamadas en tu historial

Una llamada desde un sitio web aparece en History con la etiqueta Website y el sitio de donde vino. Todo lo demás funciona como en otras llamadas: transcripción, resumen, coste, uso de herramientas y tu webhook. La dirección de la llamada es widget en los datos del webhook.

Si un visitante necesita hablar con una persona

La transferencia a una persona no está disponible en una llamada desde un sitio web. El visitante está en un navegador, así que no hay una línea telefónica que pasar a tu equipo. Si un visitante pide hablar con una persona, el agente dice que no puede transferir desde ahí y sigue ayudando. Pasar la llamada a otro agente de tu espacio de trabajo sí está disponible en estas llamadas.

Para que un visitante llegue a una persona después, puedes:

• Hacer que el agente recoja el nombre y el teléfono del visitante con un formulario, para que tu equipo le devuelva la llamada. Consulta Formularios y citas.
• Añadir la acción de Slack, para que tu equipo reciba un aviso en un canal o por mensaje directo cuando un visitante necesite a una persona. Consulta Slack.
• Poner tu horario, teléfono y correo en las instrucciones del agente, para que pueda decirle al visitante cómo contactarte. Consulta Instrucciones y frase de apertura.

La transferencia a una persona sigue funcionando en llamadas telefónicas de un número de Twilio. Consulta Transferencias por teléfono.

Cómo afecta a tu crédito

Las llamadas desde sitios web usan el mismo precio por minuto que tus demás llamadas, calculado a partir del modelo, el reconocimiento de voz y la voz del propio agente. El widget no añade ningún cargo nuevo.

• Antes de que una llamada se conecte, Phynxa reserva crédito para su primer tramo, igual que en una llamada telefónica, y lo amplía mientras la llamada dura. Al terminar se cobra el coste real y se libera el resto. Una desconexión duplicada no puede cobrar dos veces.
• Si no hay crédito suficiente, el visitante ve "Este asistente de voz no puede atender llamadas ahora". No se le informa de tu plan ni de tu saldo.
• En el plan Free, las llamadas desde sitios web cuentan como minutos reales (los 5 minutos de llamadas reales), no como minutos de prueba.
• El ajuste Longest call (10 minutos por defecto) termina la llamada con educación a esa duración. Las llamadas telefónicas conservan su propio límite, más largo.
• El límite de llamadas simultáneas de tu plan también se aplica al widget, y cada widget tiene además su propio tope de llamadas abiertas. A los visitantes que llegan cuando está lleno se les pide que lo intenten de nuevo en un minuto. Una devolución de llamada del formulario del sitio espera a que haya un hueco libre en lugar de llamar a alguien que luego sería rechazado: consulta Úsalo junto con el formulario de devolución de llamada.

Solución de problemas

El botón no aparece. Comprueba, por orden: el interruptor está activado y aparece Widget settings saved; el agente está publicado; la dirección de la página figura exactamente en Website (www. cuenta; http no); el código está en la página (mira el código fuente y busca widget.js); la página no bloquea el script con una Content Security Policy; ningún bloqueador de anuncios o de privacidad lo está quitando.

"Not seen yet" tras instalar. Comprueba que publicaste tu sitio web (Paso 3), abre una página del sitio permitido que tenga el código, en una ventana normal, y pulsa Check again. Una página en caché puede seguir siendo la antigua.

El micrófono está bloqueado. El panel lo indica. Pulsa el icono del candado o de la cámara en la barra de direcciones del navegador, permite el micrófono para el sitio y pulsa Reintentar. En un teléfono, revisa también el permiso del navegador en los ajustes del teléfono. Otra aplicación que use el micrófono (una videollamada, por ejemplo) también puede impedirlo.

"No se pudo conectar". Se cortó la conexión a internet del visitante, o algo entre él y Phynxa (un cortafuegos de empresa, una política estricta) bloquea la conexión. Deben permitirse los WebSockets (wss:).

La llamada se cortó. Pulsa Reconectar. Esto inicia una llamada nueva; no puede continuar la anterior, y la nueva se cobra como cualquier otra.

Dice que el navegador no admite llamadas de voz. El visitante necesita una versión actual de Chrome, Edge, Firefox o Safari, en una página https.

No se oye al agente. Revisa el volumen del dispositivo y que la pestaña no esté silenciada. Algunos teléfonos necesitan que se toque la pantalla antes, lo que ya hace el botón de inicio.

Úsalo junto con el formulario de devolución de llamada

Puedes usar el widget de voz y el formulario de devolución de llamada en el mismo sitio web a la vez. Son independientes: cada uno tiene su propio interruptor, sus ajustes, sus sitios permitidos y su código, y cada uno puede estar activado o desactivado sin afectar al otro.

• Instala los dos códigos. Pega el código del widget de voz y el del formulario en las mismas páginas (por ejemplo, ambos justo antes de </body>). Cada script dibuja su propio botón dentro de su propio contenedor aislado, así que ninguno puede cambiar el aspecto del otro ni de tu página. Pegar cualquiera de ellos dos veces sigue mostrándolo una sola vez.
• Dos botones, una esquina. Si ambos están en el mismo lado de la ventana, el botón de voz se coloca solo encima del botón de devolución de llamada, a 12 píxeles, así que nunca quedan uno sobre otro. Si están en lados distintos, nada se mueve. Para colocar un botón tú mismo, añade data-offset-x y data-offset-y (de 0 a 200 píxeles desde la esquina) a su código. Para desactivar el apilado automático en uno de ellos, añade data-stack="off" a su código: ese botón conserva exactamente los desplazamientos que le diste y el otro lo ignora.
• Ventanas emergentes. Abrir el formulario mientras el panel de voz está abierto no cierra el panel ni termina una llamada: el formulario se abre en el centro de la página, por encima. Cerrar uno deja el otro como estaba. Una llamada de voz continúa mientras un visitante rellena el formulario, y se puede enviar una solicitud de devolución de llamada con el panel de voz abierto.
• Sitios distintos. Cada función comprueba su propia lista de sitios permitidos, así que un sitio puede estar permitido para una y no para la otra.
• Límites compartidos. Ambas usan el mismo crédito del espacio de trabajo y el límite de llamadas simultáneas de tu plan. Una devolución de llamada espera (queda en Pending en la pestaña Callbacks) mientras estén abiertas todas las llamadas que permite tu plan, incluidas las llamadas de voz de tu sitio, y sale en cuanto termina una.
• Desactivar una. Desactiva Show the widget on my website para detener el botón de voz, o Enable Website Form para detener el formulario, y espera al mensaje de guardado. La otra sigue funcionando. Un navegador puede conservar la configuración del widget de voz hasta 30 segundos, así que su botón puede tardar ese tiempo en desaparecer.
• Si falta un botón o queda tapado. Comprueba el interruptor y los sitios permitidos de esa función, y luego mira el código fuente de la página y busca widget.js y form.js. Si un botón queda bajo un aviso de cookies o un chat, muévelo con data-offset-y. Si algo de tu página tapa ambos, sube data-z-index en cada etiqueta de script.

Apágalo o quítalo

• Pausarlo: desactiva Show the widget on my website y espera a Widget settings saved. El código puede quedarse en tu sitio; no hace nada.
• Quitarlo: borra el código de tus páginas. Eliminar el agente también elimina su widget; el código antiguo entonces no muestra nada.

Para quien administra el servidor

• No hace falta configuración adicional en una instalación normal. Las páginas y llamadas del widget usan la misma dirección que el panel, y la configuración de proxy incluida ya envía /api/* y /ws/* al backend.
• WIDGET_ALLOW_LOCALHOST=1 permite que páginas en localhost usen un widget que incluya localhost. Déjalo sin definir en producción.
• WIDGET_MAX_CONCURRENT (10 por defecto) es cuántas llamadas desde sitios web puede tener abiertas a la vez un widget. Cada dirección puede tener dos.
• SERVER_SECRET debe ser el mismo en cada instancia, y REDIS_URL debe estar definido cuando ejecutes más de una, para que el token de llamada de un solo uso del visitante y los límites funcionen en todas. Sin Redis se cuentan por instancia.
• Los tres archivos widget.js, widget-voice.js y widget-worklet.js se sirven desde el frontend con una caché corta y acceso abierto entre orígenes, que el ayudante de audio necesita.
• Las claves de los proveedores (voz, modelo de lenguaje, síntesis) se quedan en el servidor. El navegador de un visitante nunca recibe una.

Límites conocidos

• El audio en tiempo real va por un WebSocket, como en la llamada de prueba del panel. No hay WebRTC, así que las redes muy malas pueden sonar entrecortadas.
• Una llamada cortada no se puede reanudar, solo reiniciar.
• Phynxa no se ha comprobado con todos los navegadores y teléfonos. Si el widget falla en alguno, dinos cuál.
• Los textos del panel en español y árabe no han sido revisados por un hablante nativo.