Formulario de devolución de llamada web

Qué lograrás

Añadirás un botón flotante a tu propio sitio web, en la esquina inferior derecha o izquierda. Cuando un visitante lo pulsa, se abre en el centro de la página un formulario de devolución de llamada en una ventana emergente. Escribe su nombre, país y número de teléfono, indica qué le interesa, acepta que le llame un asistente de IA y elige si quiere la llamada lo antes posible o a la hora que elija. Phynxa guarda la solicitud y tu agente le llama con las mismas llamadas salientes de siempre: el mismo proveedor, las mismas instrucciones, voz, conocimiento y herramientas del agente, y el mismo crédito.

El botón y el formulario nunca hacen una llamada por sí mismos. Todo ocurre en el servidor de Phynxa: la página solo envía lo que escribió el visitante.

Requisitos previos

• Un agente que pueda hacer llamadas salientes (su dirección de llamada es Outbound o Both). Un agente que solo recibe llamadas no sirve. La dirección se cambia en la pestaña Assistant del agente.
• El agente está publicado.
• Un número desde el que llamar y un proveedor telefónico conectado (Twilio o Exotel), como en cualquier llamada saliente. Consulta Llamadas salientes.
• Crédito en tu espacio de trabajo, o minutos gratuitos 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.

Si falta algo, la tarjeta Website form dice exactamente qué corregir y el formulario no se puede activar. Al visitante nunca se le muestra un ajuste, solo "This form cannot take callback requests right now".

Crea un formulario

1. Abre el agente y elige la pestaña Website.
2. Elige la tarjeta Website Form. (La tarjeta Voice Widget de al lado es el botón de voz del sitio y funciona como antes. Pulsa de nuevo la pestaña Website en cualquier momento para volver a las dos tarjetas.)
3. En la pestaña Configuration, en Add a website, escribe la dirección de tu sitio (por ejemplo example.com) y pulsa Enter o Add.
4. Activa Enable Website Form.
5. Espera a que aparezca Form settings saved arriba a la derecha de Live Preview.

Los ajustes están en pestañas, con una Live Preview al lado: Configuration (agente, hora de la llamada, límite diario, sitios permitidos y campos), Appearance (tema, colores, posición y texto del botón), Content (los textos), Embed Code (el código y, debajo, Installation, que muestra si el formulario se ha visto en tu sitio) y Callbacks. No hay botón de guardar. Cada cambio se guarda solo un instante después de que dejas de escribir, y cuando se guarda con el interruptor activado el formulario queda activo para los visitantes. Si algo todavía no se puede guardar, 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 Form settings saved.

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

Elige el agente

Un formulario pertenece a un agente, como el widget de voz. La lista Agent de la pestaña Configuration muestra solo los agentes de tu espacio de trabajo que pueden hacer llamadas salientes. Si eliges otro agente se abre el formulario de ese agente. El agente conserva todos sus ajustes: instrucciones y personalidad, modelo, voz, audición, conocimiento, herramientas, integraciones, idioma y su número de salida. El formulario no cambia ninguno.

Si más tarde cambias el agente a solo entrante, lo pausas o lo eliminas, o quitas su proveedor telefónico, el formulario deja de aceptar solicitudes y la tarjeta explica el motivo.

Elige los campos

El formulario siempre pide:

• País, con nombres, banderas y prefijos.
• Número de teléfono, sin el prefijo del país. Phynxa lo comprueba con el país elegido y lo guarda en formato internacional (por ejemplo +447700900123).
• Consentimiento para recibir la llamada. El visitante debe marcarlo.

Puedes mostrar, ocultar y exigir los demás: First name (obligatorio por defecto), Last name, What are you interested in? y Additional details. Un campo oculto no se pide ni se guarda. Para el campo de interés puedes añadir una lista de opciones; sin opciones el visitante escribe una respuesta corta.

En Visitors can ask for a call elige si los visitantes pueden escoger ahora o a una hora elegida, solo lo antes posible o solo a una hora elegida.

El formulario no pide nada más. No hay correo electrónico ni otros datos personales.

Elige su aspecto

• Button position: esquina inferior derecha o izquierda, y Floating button label (por defecto Request a Callback; si lo vacías, el botón es redondo y muestra solo el icono del teléfono). El botón usa el color de botón que elijas más abajo.
• Theme: claro u oscuro.
• Colores de fondo, texto, principal y botón. Phynxa guarda los colores que elijas tal cual, así que revisa la vista previa para comprobar que el texto se lee bien. El texto del botón elige solo negro o blanco.
• Fuente: el formulario usa la misma fuente de sistema, limpia, que el widget de voz, sea cual sea la de tu sitio. No hay nada que configurar.
• Form title, Short description, Send button label (por defecto Request My AI Callback, el botón del formulario que lo envía) y Thank-you message.
• Consent line: la frase que el visitante acepta. El texto exacto mostrado se guarda con cada solicitud.
• Brand name y Logo address (opcionales, una imagen https).

La Preview junto a los ajustes es el botón y la ventana reales, dibujados en una página de muestra. Desde la vista previa no se envía nada, y al pulsar el botón de enviar se muestra tu mensaje de agradecimiento. Si mueves el botón a la otra esquina o lo renombras, la vista previa lo sigue.

Idioma. Las palabras propias del formulario (nombres de campos, textos de ayuda, la programación, los mensajes de error y las líneas de confirmación) están en inglés, español o árabe: el idioma del agente que hace las llamadas. El árabe se muestra de derecha a izquierda, con el botón de cerrar en la esquina superior izquierda. Para fijar un idioma en una página, añade data-lang="es" (o en, ar) al código. El título, la descripción, el botón, la línea de consentimiento y el mensaje de agradecimiento son tus propias palabras y siempre se muestran tal como los escribiste; si dejas uno en su texto original en inglés, se muestra en el idioma del formulario. La vista previa también usa el idioma del agente. Escríbelos en el idioma de tus visitantes.

Elige los sitios permitidos

El formulario aparece solo en los sitios que enumeras, con las mismas reglas que el widget de voz:

Los subdominios nunca son de confianza salvo que escribas la línea con *., y solo funcionan sitios https. La comprobación se hace en el servidor en cada carga y cada envío. Los navegadores indican al servidor desde qué sitio viene una solicitud y una página no puede cambiarlo, pero un programa que no es un navegador puede afirmar ser cualquier sitio, así que la lista no es la única defensa: consulta Protección contra abusos.

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.

Instala el formulario en tu sitio web

Instalar significa pegar un fragmento de código en tu sitio web. El botón se dibuja en la esquina de la ventana, así que da igual en qué punto de la página esté el código: ponlo en cada página donde quieras que aparezca el botón.

Paso 1. Obtén tu código

Abre la pestaña Embed Code y pulsa Copy. El código es así, con tu propio ID de formulario. Contiene solo tu ID público: ni claves, ni contraseñas, ni tokens, y el ID por sí solo no permite hacer ninguna llamada.

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

Paso 2. Pégalo en tus páginas

El mejor lugar es justo antes de la etiqueta de cierre </body>, o en un pie de página o plantilla que compartan todas las páginas, para que el botón aparezca en todas. Si el botón queda donde ya hay un aviso de cookies o un chat, añade data-offset-x="80" y data-offset-y="80" (una distancia desde la esquina en píxeles, de 0 a 200) al código, y data-z-index="..." si algo de tu página lo tapa. data-lang="en", "es" o "ar" fija el idioma del formulario (consulta Elige su aspecto).

• HTML simple: pégalo en el archivo de la página justo encima de </body> y sube el archivo.
• WordPress: usa un plugin de código como WPCode y pega el código en su casilla Footer, o añade un bloque HTML personalizado a una página.
• Next.js y React: añade un Script (o un pequeño componente que añada la etiqueta script) una sola vez, en tu layout. Conserva el atributo data-form-id. La pestaña Embed Code trae versiones listas para copiar en HTML, React y Next.js: elige la tuya sobre el código.
• Shopify, Wix, Squarespace, Webflow: usa el ajuste de código personalizado o código del pie del constructor y pega el código.
• Google Tag Manager: sirve una etiqueta HTML personalizado en All Pages.

Los nombres de los menús cambian de vez en cuando. Busca las mismas palabras cerca.

El botón y la ventana se dibujan en un contenedor aislado, igual que el widget de voz, así que los estilos de tu sitio no pueden romperlos y no añaden estilos a tu página. Cargar el código dos veces, o pegarlo dos veces para un mismo formulario, muestra un solo botón. Dos formularios distintos en una página muestran dos botones, así que da un desplazamiento a uno de ellos. El botón del widget de voz en el mismo lado se coloca solo encima del botón del formulario: consulta Junto al widget de voz.

Paso 3. Publica y comprueba

Publica o despliega tu sitio, vacía cualquier caché y abre la página en uno de los sitios que enumeraste. En la pestaña Embed Code, en el panel Installation bajo el código, Not seen yet pasa a Installed con la dirección del sitio. Pulsa Check again si no ha cambiado. Copiar el código no cuenta: solo cambia cuando el navegador de un visitante ha cargado tu página con el código.

Si tu sitio tiene una Content Security Policy, permite la dirección de Phynxa en scripts (script-src) y conexiones (connect-src), y las imágenes https si usas un logotipo (img-src).

Qué ve el visitante y qué pasa después

1. El visitante pulsa el botón flotante. El formulario se abre en una ventana en el centro de la página, con la página atenuada detrás. Lo rellena y marca el consentimiento. Los errores se muestran junto al campo.
2. Si lo permites, elige As soon as possible o Schedule a call. Para una llamada programada elige una fecha (dentro de los próximos 30 días) y una hora. El formulario muestra su zona horaria, tomada de su dispositivo, y repite la elección con palabras ("We will call you on ...").
3. Al pulsar el botón se envía la solicitud. Pulsar otra vez mientras se envía, o enviar dos veces el mismo formulario tras un fallo de conexión, es una sola solicitud.
4. Ve tu mensaje de agradecimiento dentro de la ventana y, en una llamada programada, la fecha y hora confirmadas en su propia zona. Al cerrar la ventana después, la siguiente vez se abre un formulario nuevo.

La ventana se cierra con su botón ×, pulsando en la zona atenuada de alrededor o con Escape. Lo que el visitante escribió se conserva si la cierra sin enviar y la abre otra vez. En un teléfono se ajusta a la pantalla, y cuando el formulario es más alto que la ventana se desplaza dentro de ella, con el botón de cerrar siempre a la vista.

Si el mismo número ya tiene una solicitud en espera en este formulario, no se crea otra y se avisa al visitante.

Llamadas inmediatas

Una solicitud inmediata se guarda y se despierta de inmediato el proceso que realiza las llamadas programadas, así que normalmente la llamada sale en segundos. Si otro de tus servidores tiene ese proceso, sale en menos de medio minuto. Que pueda salir depende también de tu crédito y de los límites de llamadas simultáneas de tu plan.

Llamadas programadas y zonas horarias

La hora y la zona horaria del visitante se convierten en un instante exacto (UTC) en el servidor y se guardan con el nombre de la zona. El servidor rechaza una hora pasada, con menos de 10 minutos de margen, a más de 30 días, o que no existe en esa zona (la hora que se salta al cambiar el reloj). La llamada no se hace antes de ese instante. Si el servidor estaba caído en ese momento, la llamada sale al volver, con hasta 2 horas de retraso. Pasado ese tiempo la solicitud se marca Failed con el motivo not placed in time, en vez de llamar a una hora que nadie pidió. Después puedes usar Retry.

Phynxa no tiene un horario de llamadas para todo el espacio de trabajo, así que un visitante puede elegir cualquier hora. Si algunas horas no te convienen, cancela o reprograma esas solicitudes desde la pestaña Callbacks.

Consentimiento e información del visitante

• El visitante debe marcar la casilla de consentimiento. Un envío sin ella lo rechaza el servidor, sea lo que sea lo que envió la página.
• Cada solicitud guarda el momento en que aceptó y el texto exacto que aceptó, para que puedas demostrar a qué dio su consentimiento.
• Phynxa guarda lo que escribió el visitante (nombre, país, teléfono, interés, detalles), la elección de hora, el sitio web de origen y el estado de la llamada. No guarda su dirección IP, correo electrónico ni datos de su dispositivo.
• Todo lo escrito se trata como texto simple. Al agente se le dice que es información sobre la persona y no instrucciones, así que un visitante no puede cambiar el comportamiento del agente con lo que escribe.
• Un miembro de tu espacio de trabajo ve la solicitud con el teléfono parcialmente oculto. Propietarios y administradores ven el número completo.
• Al eliminar el agente se eliminan su formulario y sus solicitudes, y al eliminar tu cuenta se eliminan todas.
• Un número de tu lista de no llamar (un contacto de Contacts con estado blocked) nunca se llama.

Eres responsable de tener una base legal para llamar a las personas, de lo que diga tu línea de consentimiento y de las normas sobre llamadas automatizadas donde viven tus visitantes. Phynxa guarda el consentimiento; no decide qué debes pedir.

El agente en la llamada

La llamada se hace con tu agente como siempre. Antes de hablar, al agente se le dice que es una devolución de llamada que la persona pidió en el formulario de tu sitio, su nombre, qué le interesa y qué escribió, y que debe decir quién es y ayudarle con eso. No se le pasa nada más del visitante. La frase de apertura, la voz y todo lo demás son los del propio agente.

La llamada aparece en History como llamada saliente con la etiqueta Website form, con su transcripción, resumen y coste como cualquier otra.

Gestiona las devoluciones de llamada

Abre la pestaña Callbacks del panel del formulario. Elige This agent o All agents y filtra por estado. Cada fila muestra el visitante, teléfono, interés, hora y zona de la llamada, estado y resultado. Selecciona una fila para ver los detalles completos, con lo que escribió y un enlace al registro de la llamada.

Como propietario o administrador puedes:

• Cancelar una devolución de llamada Pending o Scheduled. Después nunca se marca.
• Reprogramar una Pending o Scheduled a otra fecha y hora. Es la misma solicitud, así que nunca hay una segunda llamada.
• Reintentar una Failed. Vuelve a Pending y se llama lo antes posible. Se rechaza si el agente no puede llamar ahora o si el mismo número ya tiene otra solicitud en espera.

Una Processing o Calling no se puede cancelar ni mover: está al teléfono.

Si el visitante no contestó, Phynxa lo intenta una vez más unos 30 minutos después y luego la marca Failed (not answered). Si no se pudo contactar con el proveedor telefónico, también lo intenta una vez más. Los demás fallos no se reintentan solos. Cada intento se marca una sola vez por muchas veces que se reinicie el servidor: si el servidor se detiene justo cuando se hace una llamada, la solicitud se marca Failed (not retried, to avoid calling twice) y tú decides si usar Retry.

Desactivar el formulario detiene las solicitudes nuevas pero no cancela las ya aceptadas. Cancélalas desde la pestaña Callbacks si no quieres que se llamen.

Cómo afecta a tu crédito

Una devolución de llamada es una llamada saliente normal. Su precio por minuto se calcula con el modelo, la audición y la voz del propio agente, sin añadir nada por el formulario.

• Antes de aceptar la solicitud de un visitante, Phynxa comprueba que el espacio de trabajo puede atender llamadas. Si no, el visitante ve "This form cannot take callback requests right now" y no se guarda nada.
• Antes de cada llamada se aparta crédito para su primer tramo, igual que en cualquier llamada saliente. Al terminar la llamada se cobra el coste real y se libera el resto. Si nadie contesta, el crédito se libera y no se cobra nada. Una llamada solo se puede cobrar una vez.
• Si tu crédito se ha agotado cuando toca la llamada, la solicitud se marca Failed (not enough credit). Añade crédito y pulsa Retry.
• En el plan Free la llamada cuenta como minutos reales.
• Se aplica el límite de llamadas simultáneas de tu plan. Una solicitud espera como Pending mientras estén abiertas todas las llamadas que permite tu plan (incluidas las llamadas de voz del widget del sitio) y se marca en cuanto termina una.

Todo se calcula en el servidor. Nada de lo que envíe el navegador puede cambiar un precio ni saltarse una comprobación.

Protección contra abusos

Varias capas impiden que un script gaste tu crédito, porque el sitio web no es la única defensa:

• La página pide un token de corta duración al cargarse y se rechaza un envío sin uno válido. Una persona no puede rellenar el formulario en menos de tres segundos.
• Un campo oculto que las personas nunca ven atrapa a los scripts que rellenan todos los campos.
• Cada conexión a internet (dirección) puede tener dos solicitudes aceptadas por un formulario cada hora, y cada número de teléfono tres al día; un formulario admite como máximo 60 por hora y un espacio de trabajo 300, y un formulario admite como máximo el límite diario que fijes. Solo cuenta una solicitud que realmente se guarda: un error al escribir, la repetición de una solicitud ya enviada o un rechazo por otro motivo no gasta un lugar. Al visitante que supera el límite se le dice que vuelva a intentarlo en aproximadamente una hora. Si tu servidor está detrás de más de un proxy (por ejemplo un CDN delante de Caddy), define TRUST_PROXY_HOPS para que el límite vea la dirección propia del visitante; si no, todos los visitantes compartirán una.
• Un número puede pedir una devolución de llamada como máximo tres veces en 24 horas.
• Cada formulario tiene un Daily limit (por defecto 200 solicitudes en 24 horas, en la pestaña Configuration).
• El servidor decide el agente, el espacio de trabajo y el estado. El navegador no puede elegirlos.

Junto al widget de voz

El formulario y el widget de voz pueden estar en el mismo sitio web a la vez, cada uno con su propio interruptor, ajustes y sitios permitidos. Si los dos botones están en el mismo lado de la ventana se apilan en lugar de solaparse; añade data-stack="off" al código de un script si colocas el botón tú mismo. Abrir el formulario no cierra un panel de voz ni termina una llamada, y una devolución de llamada espera como Pending mientras todas las llamadas de tu plan están en uso. Los detalles completos están en Úsalo junto con el formulario de devolución de llamada, en la guía del widget de voz.

Solución de problemas

El botón no aparece. Comprueba, en orden: el interruptor está activado y se muestra Form settings saved; la dirección de la página está en Allowed websites exactamente (www. cuenta; http no); el código está en la página (busca form.js en el código fuente); una Content Security Policy no lo bloquea. Si el agente no puede hacer una llamada ahora (en pausa, solo entrante, sin número o proveedor) el botón aparece igualmente, pero al enviar el formulario se muestra "cannot take callback requests right now" y no se guarda nada.

"Not seen yet" tras instalar. Comprueba que publicaste tu sitio, abre una página de un sitio permitido que tenga el código y pulsa Check again.

El visitante ve "cannot take callback requests right now". El agente no puede hacer una llamada (en pausa, solo entrante, sin número o proveedor) o el espacio de trabajo no tiene crédito. La tarjeta Website form del panel dice cuál.

Una solicitud está Failed. Ábrela: se muestra el motivo. Not enough credit: añade crédito y Retry. The agent was deleted, paused or can no longer make outbound calls: corrige el agente y Retry. On your do-not-call list: el número está bloqueado en Contacts. Not answered: la persona no contestó tras dos intentos. Not placed in time: el servidor no pudo llamar en las dos horas siguientes a la hora elegida. Un mensaje del proveedor se muestra tal como llegó.

Una solicitud está Failed y dice que Twilio no confirmó la llamada. El proveedor telefónico no respondió a tiempo, así que Phynxa no puede saber si la llamada salió. No se reintenta sola, para no llamar dos veces a la persona. Revisa el registro de llamadas de tu proveedor para ese número: si no se hizo ninguna llamada, pulsa Retry.

Una solicitud sigue en Calling mucho tiempo. Una llamada marcada que nunca se conectó pasa a Failed (not answered) unos minutos después.

Un visitante dice que no recibió la llamada. Busca su solicitud en Callbacks: su estado y motivo dicen qué pasó. Si dice Completed, la llamada fue contestada y tiene un registro en History.

Para quien administra el servidor

• Ningún servicio, cola ni worker nuevo. Las devoluciones de llamada las hace el proceso de llamadas programadas que ya se ejecuta dentro del backend (cada 30 segundos, e inmediatamente para una solicitud inmediata). Con varias instancias, solo la que tiene el bloqueo hace las llamadas, como antes.
• Dos migraciones aditivas, 0012_website_forms (dos tablas nuevas y una columna nueva en calls) y 0013_form_popup_button (dos columnas nuevas en la tabla de formularios: la esquina y el texto del botón). Nada existente cambia, así que volver a la versión anterior es seguro.
• Ninguna variable de entorno nueva. Se aplican las existentes: PUBLIC_URL (la dirección a la que llama de vuelta tu proveedor telefónico), WIDGET_ALLOW_LOCALHOST=1 (solo desarrollo, permite que un formulario enumere localhost), SERVER_SECRET (igual en todas las instancias para que los tokens se verifiquen en todas), REDIS_URL (cuando ejecutas más de una instancia, para compartir los límites) y TRUST_PROXY=1 detrás de un proxy, para que los límites cuenten a cada visitante y no al proxy.
• form.js lo sirve el frontend con una caché corta y acceso cross-origin abierto, como los scripts del widget. El navegador del visitante llama a /api/form/... en la misma dirección; la configuración del proxy ya reenvía /api/*.
• Las llamadas se hacen por Twilio o Exotel exactamente como otras llamadas salientes. Otros proveedores no se usan para llamadas salientes, así que un formulario no puede usarlos.

Límites conocidos

• Phynxa no ha hecho una llamada real con este formulario en las pruebas: en las pruebas automáticas el proveedor telefónico se sustituye por un doble. Haz tú una solicitud de prueba antes de depender de él (consulta los pasos de abajo).
• Las palabras fijas del formulario solo existen en inglés, español y árabe. Un agente que habla otro idioma muestra el formulario en inglés salvo que indiques data-lang.
• La comprobación del teléfono confirma que el número parece correcto para el país y lo guarda en formato internacional; no puede saber si un número bien formado pertenece a alguien.
• No hay horario de llamadas. Un visitante puede elegir cualquier hora en los próximos 30 días.
• El botón y la ventana no se han comprobado en todos los navegadores, constructores de sitios y teléfonos.
• La traducción al español no ha sido revisada por un hablante nativo.

Pruébalo de principio a fin

1. Abre un agente de salida, elige Website y luego Website Form, añade tu sitio y activa el formulario.
2. Pega el código en una página de prueba de ese sitio y ábrela. Espera a Installed.
3. Pulsa el botón flotante, rellena el formulario con tu propio número, marca el consentimiento, elige As soon as possible y envíalo.
4. Abre la pestaña Callbacks: la solicitud pasa de Pending a Calling. Suena tu teléfono y el agente dice que devuelve tu solicitud.
5. Tras la llamada la solicitud está Completed y la llamada aparece en History con la etiqueta Website form.
6. Repite con Schedule a call unos minutos más tarde para comprobar la hora y la zona.