Formularios de contacto y mensajes

Contact Form y Contact Messages son funciones de primer nivel de WebBlocks CMS. Utilice el bloque nativo contact_form para las páginas de contacto en lugar de Trusted HTML, marcado de formulario en bruto o alternativas con mailto:.

Esta guía consolida el comportamiento de Contact Form y Contact Messages orientado al usuario que está documentado en los contratos de bloques, los contratos de renderizado público, la documentación de la Internal Content API y el README. No define nuevo comportamiento en tiempo de ejecución.

El bloque Contact Form renderiza un formulario público real y almacena en el CMS los mensajes aceptados. Contact Messages ofrece a los administradores una pantalla de revisión de esos envíos, que incluye el estado, las señales de revisión de spam, el estado de notificación y los detalles seguros de los fallos de entrega.

El CMS trata el almacenamiento y la notificación por correo electrónico como asuntos independientes:

• los envíos reales aceptados se almacenan antes de intentar la notificación
• la notificación puede completarse, fallar u omitirse sin que ello cambie el hecho de que el CMS aceptó el envío público
• los visitantes públicos deben ver un mensaje genérico de éxito o de validación, no la puntuación de spam ni los detalles internos de la entrega

Añada el bloque desde el selector de bloques del Page Builder. El identificador nativo del bloque es:

El bloque Contact Form no es un contenedor de bloques hijos. Es el propietario de la superficie pública del formulario y no acepta bloques de contenido anidados como modelo de composición normal.

Una página de contacto típica utiliza contenido estructurado alrededor del formulario nativo:

Las herramientas de IA/operador deben construir el mismo tipo de estructura una vez que el descubrimiento en vivo confirme los identificadores disponibles. No deben crear formularios con Trusted HTML, marcado <form> en bruto ni enlaces mailto: cuando contact_form exista en la instalación de CMS de destino.

El texto visible es traducible:

• title o encabezado
• content o texto de introducción
• submit_label
• success_message

La configuración operativa compartida se encuentra en los ajustes del bloque:

• recipient_email
• send_email_notification
• store_submissions

Mantenga separados el texto editorial y el enrutamiento operativo. El texto del formulario puede variar según el idioma (locale), mientras que los ajustes de destinatario y notificación se mantienen compartidos para el bloque.

El renderizador público genera un formulario nativo del navegador que envía los datos a:

El formulario está protegido con CSRF y valida los campos habituales del visitante.

Campos obligatorios:

• name
• email
• message

Campo opcional:

• subject

Campo de comprobación antispam generado por el renderizador:

• _form_check_name metadatos firmados
• form_check_{token} campo de comprobación generado

El renderizador crea estos campos automáticamente. No los cree manualmente en el contenido, en HTML en bruto ni en las cargas útiles de la API. El campo de comprobación no forma parte de la entrada normal del visitante, y el antiguo campo website ya no es el contrato público de Contact Form.

Los envíos con el campo de comprobación relleno reciben el mismo comportamiento genérico de éxito que un envío aceptado normal, pero no se almacenan ni activan la notificación. Los envíos automatizados muy rápidos se tratan del mismo modo. Los visitantes públicos no deben recibir diagnósticos de spam ni de entrega.

Los envíos reales aceptados se almacenan antes de intentar la notificación por correo electrónico.

Ruta de administración:

Contact Messages es una pantalla de revisión para administradores. No es un listado público ni una API pública de entrega.

La pantalla de administración permite a los usuarios del CMS revisar los envíos a nivel de guía de usuario:

• el estado del mensaje, por ejemplo nuevo, leído, respondido, archivado o spam
• el contexto de la página de origen cuando está disponible
• la puntuación de spam y las etiquetas de motivo de spam para su revisión
• si la notificación se omitió, se envió, falló o está pendiente
• detalles seguros del fallo cuando la entrega de la notificación falla

El estado de notificación por correo electrónico se refiere únicamente al comportamiento de la notificación:

• Sent significa que el CMS entregó el mensaje al transporte de correo configurado sin excepciones. No garantiza la entrega en la bandeja de entrada.
• Failed significa que se intentó un envío real de notificación y Laravel informó de una excepción. El detalle guardado está saneado y no debe incluir contraseñas, tokens, el .env en bruto ni trazas de pila.
• Skipped significa que no se intentó la notificación, normalmente porque el bloque la tenía desactivada.
• Not configured significa que no se intentó la notificación porque no había ningún destinatario disponible, el mailer es log, array o null, o los ajustes SMTP están lo bastante incompletos como para que la entrega saliente no sea posible.
• Pending se reserva para los registros que aún no han tenido un intento de notificación o una resolución.

Los mensajes guardados más antiguos pueden tener el estado de notificación inferido a partir de los campos heredados de envío/error. El CMS no reescribe automáticamente esos registros históricos.

Contact Messages también sigue el comportamiento compartido de los listados de administración para la eliminación masiva de elementos seleccionados donde esté disponible. Trate la eliminación como una acción de limpieza administrativa, no como parte del tratamiento normal del formulario público.

La gestión del spam tiene dos capas.

La capa del campo de comprobación generado por el renderizador es de descarte inmediato:

• el campo oculto generado form_check_{token} debe permanecer vacío para los visitantes normales
• los envíos con el campo de comprobación relleno reciben un éxito genérico
• los envíos con el campo de comprobación relleno no se almacenan
• los envíos con el campo de comprobación relleno no activan la notificación

Los envíos que superan el campo de comprobación generado aún pueden puntuarse de forma conservadora. Ejemplos actuales de señales de puntuación:

• alta densidad de enlaces o múltiples enlaces
• lenguaje de captación comercial
• combinaciones genéricas de asunto y mensaje de estilo comercial
• envíos repetidos desde la misma dirección IP

El spam puntuado se conserva intencionadamente con estado de spam para su revisión por parte del administrador. No describa la eliminación automática de spam como comportamiento actual. Un umbral configurable de descarte automático es solo una posible dirección futura tras observar datos de producción.

La notificación de Contact Form utiliza este orden de destinatarios:

1. recipient_email a nivel de bloque
2. El destinatario de contacto predeterminado del sitio actual, en Edit Site -> Contact
3. CONTACT_RECIPIENT_EMAIL
4. MAIL_FROM_ADDRESS como última reserva segura

El éxito del almacenamiento es independiente del éxito de la notificación. Una respuesta pública de éxito significa que el CMS aceptó el flujo del mensaje, no necesariamente que la entrega del correo electrónico se completara. Los administradores deben consultar Contact Messages para ver el estado de notificación y los detalles seguros del fallo.

Las notificaciones de Contact Form utilizan la entrega de correo de Laravel. Los ajustes SMTP típicos de .env son:

MAIL_* controla el transporte de correo de Laravel. MAIL_FROM_ADDRESS es la dirección de remitente segura de reserva y la última reserva segura de destinatario. CONTACT_RECIPIENT_EMAIL es opcional y solo se utiliza cuando los destinatarios del bloque y del sitio están vacíos. Para el enrutamiento normal del sitio, prefiera el destinatario de contacto a nivel de sitio en Site -> Edit -> Contact.

Utilice un mailer saliente real, como SMTP, para las notificaciones en producción. MAIL_MAILER=log, MAIL_MAILER=array y MAIL_MAILER=null son útiles para desarrollo o pruebas, pero Contact Messages los muestra como no configurados en lugar de enviados, porque no se intentó ninguna notificación saliente real.

Después de editar los ajustes de correo de .env en una instalación de producción o de paquete, limpie la configuración en caché cuando el almacenamiento en caché de la configuración pueda estar activo:

Para el desarrollo local, utilice un capturador SMTP local o una cuenta SMTP de prueba de confianza. Evite probar la entrega de contacto contra buzones personales o de producción, salvo que el operador haya configurado ese entorno de forma intencionada.

El comando de diagnóstico es:

Utilice el ID de un bloque Contact Form concreto para inspeccionar la cadena de destinatarios de reserva de ese bloque:

Utilice una comprobación de envío SMTP controlada solo cuando la dirección de prueba de destino sea intencionada:

Los diagnósticos no deben imprimir contraseñas, tokens, secretos de correo ni configuración sensible en bruto. Los detalles de las notificaciones fallidas, omitidas y no configuradas pueden consultarse en Contact Messages. Trate Contact Messages como la fuente de verdad de los envíos almacenados y de su estado de notificación.

Antes de publicar o anunciar una página de contacto pública:

1. Confirme que el inicio de sesión de administrador funciona.
2. Confirme que la identidad del sitio y los ajustes de dominio son correctos.
3. Configure la entrega MAIL_* o los ajustes de correo del sistema aprobados.
4. Configure el destinatario de contacto, preferiblemente en Site -> Edit -> Contact.
5. Ejecute php artisan contact:mail-diagnose.
6. Previsualice o publique una página que contenga el bloque nativo contact_form.
7. Envíe un mensaje de prueba con nombre, correo electrónico, asunto y mensaje.
8. Confirme que /webadmin/contact-messages muestra el mensaje almacenado.
9. Revise el estado de notificación y los posibles detalles seguros del fallo.

Si la notificación falla pero el mensaje se almacena, trátelo como un problema de entrega de correo, no como un envío fallido del formulario público.

La Internal Content API está destinada a herramientas de IA/operador de confianza. No es una API pública de entrega ni una integración con un proveedor de IA.

Las herramientas de IA/operador deben comenzar con el descubrimiento en vivo:

Después, utilice los enlaces descubiertos para consultar los contratos actuales:

GET /webadmin/api/examples/contact-page muestra el uso nativo de contact_form. Las herramientas de IA/operador no deben adivinar identificadores ni construir formularios de contacto con Trusted HTML, marcado de formulario en bruto o enlaces mailto: cuando el bloque nativo Contact Form esté disponible.

La aplicación de contenido sigue siendo borrador primero y no publica de forma predeterminada. Los operadores deben validar los planes, aplicarlos solo tras una aprobación explícita, previsualizar la página en borrador y dejar la publicación en manos de una persona o de un flujo de trabajo aprobado explícitamente.

• Contratos de tipos de bloque
• Marcado de renderizado público de bloques
• Contratos del renderizador
• Internal Content API
• Descubrimiento de API
• Guía de creación de páginas con IA
• Inventario de funciones