Moduli di contatto e messaggi

Contact Form e Contact Messages sono funzionalità di prima classe di WebBlocks CMS. Utilizzate il blocco nativo contact_form per le pagine di contatto invece di Trusted HTML, markup di form grezzo o soluzioni di ripiego con mailto:.

Questa guida consolida il comportamento di Contact Form e Contact Messages rivolto all'utente, documentato nei contratti dei blocchi, nei contratti di rendering pubblico, nella documentazione della Internal Content API e nel README. Non definisce nuovi comportamenti di runtime.

Panoramica

Il blocco Contact Form esegue il rendering di un vero form pubblico e memorizza nel CMS i messaggi accettati. Contact Messages offre agli amministratori una schermata di revisione di questi invii, che include stato, segnali di revisione dello spam, stato della notifica e dettagli sicuri sugli errori di consegna.

Il CMS tratta l'archiviazione e la notifica via e-mail come aspetti distinti:

  • gli invii reali accettati vengono memorizzati prima che venga tentata la notifica
  • la notifica può riuscire, fallire o essere saltata senza modificare il fatto che il CMS ha accettato l'invio pubblico
  • i visitatori pubblici devono vedere un riscontro generico di successo o di validazione, non il punteggio di spam o i dettagli interni della consegna

Aggiungere un blocco Contact Form

Aggiungete il blocco dal selettore di blocchi del Page Builder. L'handle nativo del blocco è:

contact_form

Il blocco Contact Form non è un contenitore di blocchi figli. Possiede la superficie pubblica del form e non accetta blocchi di contenuto annidati come normale modello di composizione.

Una tipica pagina di contatto utilizza contenuto strutturato attorno al form nativo:

main slot
  section
    container
      content_header or hero
      contact_form

Gli strumenti IA/operatore devono costruire lo stesso tipo di struttura dopo che la discovery in tempo reale ha confermato gli handle disponibili. Non devono creare form con Trusted HTML, markup <form> grezzo o link mailto: quando contact_form esiste nell'installazione CMS di destinazione.

Campi del blocco Contact Form

Il testo visibile è traducibile:

  • title o intestazione
  • content o testo introduttivo
  • submit_label
  • success_message

Le impostazioni operative condivise si trovano nelle impostazioni del blocco:

  • recipient_email
  • send_email_notification
  • store_submissions

Mantenete separati il testo editoriale e l'instradamento operativo. Il testo del form può variare in base alla lingua (locale), mentre le impostazioni di destinatario e notifica restano condivise per il blocco.

Comportamento dell&#039;invio pubblico

Il renderer pubblico genera un form nativo del browser che invia i dati a:

POST /contact-messages

Il form è protetto da CSRF e valida i normali campi del visitatore.

Campi obbligatori:

  • name
  • email
  • message

Campo opzionale:

  • subject

Campo di controllo antispam generato dal renderer:

  • _form_check_name metadati firmati
  • form_check_{token} campo di controllo generato

Il renderer crea questi campi automaticamente. Non createli manualmente nel contenuto, in HTML grezzo o nei payload dell'API. Il campo di controllo non fa parte del normale input del visitatore e il vecchio campo website non è più il contratto pubblico di Contact Form.

Gli invii con il campo di controllo compilato ricevono lo stesso comportamento generico di successo di un normale invio accettato, ma non vengono memorizzati e non attivano la notifica. Gli invii automatizzati molto rapidi vengono gestiti allo stesso modo. I visitatori pubblici non devono ricevere diagnostica su spam o consegna.

Archiviazione e amministrazione di Contact Messages

Gli invii reali accettati vengono memorizzati prima che venga tentata la notifica via e-mail.

Percorso di amministrazione:

/webadmin/contact-messages

Contact Messages è una schermata di revisione per amministratori. Non è un elenco pubblico né un'API pubblica di consegna.

La schermata di amministrazione consente agli utenti del CMS di rivedere gli invii a livello di guida utente:

  • lo stato del messaggio, ad esempio nuovo, letto, con risposta, archiviato o spam
  • il contesto della pagina di origine, quando disponibile
  • il punteggio di spam e le etichette del motivo dello spam per la revisione
  • se la notifica è stata saltata, inviata, è fallita o è in attesa
  • dettagli sicuri sull'errore quando la consegna della notifica fallisce

Lo stato della notifica via e-mail riguarda esclusivamente il comportamento della notifica:

  • Sent significa che il CMS ha consegnato il messaggio al trasporto di posta configurato senza eccezioni. Non garantisce la consegna nella casella di posta.
  • Failed significa che è stato tentato un invio reale della notifica e Laravel ha segnalato un'eccezione. Il dettaglio salvato è sanificato e non deve includere password, token, il file .env grezzo o stack trace.
  • Skipped significa che la notifica non è stata tentata, di solito perché il blocco l'ha disattivata.
  • Not configured significa che la notifica non è stata tentata perché non era disponibile alcun destinatario, il mailer è log, array o null, oppure le impostazioni SMTP sono incomplete al punto da rendere impossibile la consegna in uscita.
  • Pending è riservato ai record per i quali non si è ancora verificato un tentativo di notifica o una risoluzione.

I messaggi salvati meno recenti possono avere lo stato di notifica dedotto dai vecchi campi di invio/errore. Il CMS non riscrive automaticamente questi record storici.

Contact Messages segue inoltre il comportamento condiviso degli elenchi di amministrazione per l'eliminazione in blocco degli elementi selezionati, dove disponibile. Considerate l'eliminazione come un'azione di pulizia amministrativa, non come parte della normale gestione del form pubblico.

Gestione dello spam

La gestione dello spam ha due livelli.

Il livello del campo di controllo generato dal renderer prevede lo scarto immediato:

  • il campo nascosto generato form_check_{token} deve restare vuoto per i visitatori normali
  • gli invii con il campo di controllo compilato ricevono un successo generico
  • gli invii con il campo di controllo compilato non vengono memorizzati
  • gli invii con il campo di controllo compilato non attivano la notifica

Gli invii che superano il campo di controllo generato possono comunque ricevere un punteggio prudenziale. Esempi attuali di segnali di punteggio:

  • densità elevata di link o link multipli
  • linguaggio di contatto commerciale
  • combinazioni generiche di oggetto e messaggio in stile vendita
  • invii ripetuti dallo stesso indirizzo IP

Lo spam con punteggio viene volutamente conservato con stato di spam per la revisione da parte dell'amministratore. Non descrivete l'eliminazione automatica dello spam come comportamento attuale. Una soglia configurabile di scarto automatico è solo una possibile direzione futura, dopo l'osservazione dei dati di produzione.

Catena di fallback della notifica via e-mail

La notifica di Contact Form utilizza questo ordine di destinatari:

  1. recipient_email a livello di blocco
  2. Il destinatario Contact predefinito del sito corrente, da Edit Site -> Contact
  3. CONTACT_RECIPIENT_EMAIL
  4. MAIL_FROM_ADDRESS come ultimo fallback sicuro

Il successo dell'archiviazione è distinto dal successo della notifica. Una risposta pubblica di successo indica che il CMS ha accettato il flusso del messaggio, non necessariamente che la consegna dell'e-mail sia riuscita. Gli amministratori devono controllare Contact Messages per lo stato della notifica e i dettagli sicuri sugli errori.

Configurazione dell&#039;e-mail

Le notifiche di Contact Form utilizzano la consegna della posta di Laravel. Le impostazioni SMTP tipiche in .env sono:

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=no-reply@example.com
MAIL_FROM_NAME="Site Name"

CONTACT_RECIPIENT_EMAIL=contact@example.com

MAIL_* controlla il trasporto di posta di Laravel. MAIL_FROM_ADDRESS è l'indirizzo mittente sicuro di ripiego e l'ultimo fallback sicuro per il destinatario. CONTACT_RECIPIENT_EMAIL è opzionale e viene utilizzato solo quando i destinatari del blocco e del sito sono vuoti. Per il normale instradamento del sito, preferite il destinatario Contact a livello di sito in Site -> Edit -> Contact.

Per le notifiche in produzione utilizzate un mailer in uscita reale, come SMTP. MAIL_MAILER=log, MAIL_MAILER=array e MAIL_MAILER=null sono utili per lo sviluppo o i test, ma Contact Messages li mostra come non configurati anziché inviati, perché non è stato tentato alcun invio reale in uscita.

Dopo aver modificato le impostazioni di posta in .env su un'installazione di produzione o da pacchetto, svuotate la configurazione memorizzata nella cache quando il caching della configurazione potrebbe essere attivo:

php artisan optimize:clear

Risoluzione dei problemi e diagnostica

Per lo sviluppo locale, utilizzate un catcher SMTP locale o un account SMTP di test affidabile. Evitate di testare la consegna dei contatti su caselle personali o di produzione, a meno che l'operatore non abbia configurato intenzionalmente quell'ambiente.

Il comando di diagnostica è:

php artisan contact:mail-diagnose

Utilizzate l'ID di uno specifico blocco Contact Form per esaminare il fallback dei destinatari di quel blocco:

php artisan contact:mail-diagnose --block=ID

Utilizzate una verifica di invio SMTP controllata solo quando l'indirizzo di test di destinazione è intenzionale:

php artisan contact:mail-diagnose --send-test=address@example.com

La diagnostica non deve stampare password, token, segreti di posta o configurazioni sensibili grezze. I dettagli delle notifiche fallite, saltate e non configurate possono essere esaminati da Contact Messages. Considerate Contact Messages come la fonte di verità per gli invii memorizzati e il loro stato di notifica.

Checklist di preparazione alla pubblicazione

Prima di pubblicare o annunciare una pagina di contatto pubblica:

  1. Verificate che il login amministratore funzioni.
  2. Verificate che l'identità del sito e le impostazioni del dominio siano corrette.
  3. Configurate la consegna MAIL_* o le impostazioni di posta di sistema approvate.
  4. Configurate il destinatario Contact, preferibilmente in Site -> Edit -> Contact.
  5. Eseguite php artisan contact:mail-diagnose.
  6. Visualizzate in anteprima o pubblicate una pagina che contiene il blocco nativo contact_form.
  7. Inviate un messaggio di prova con nome, e-mail, oggetto e messaggio.
  8. Verificate che /webadmin/contact-messages mostri il messaggio memorizzato.
  9. Esaminate lo stato della notifica ed eventuali dettagli sicuri sugli errori.

Se la notifica fallisce ma il messaggio viene memorizzato, trattatelo come un problema di consegna della posta, non come un invio fallito del form pubblico.

Internal Content API e supporto per operatori IA

La Internal Content API è destinata a strumenti IA/operatore affidabili. Non è un'API pubblica di consegna né un'integrazione con un fornitore di IA.

Gli strumenti IA/operatore devono iniziare con la discovery in tempo reale:

GET /webadmin/api

Utilizzate poi i link individuati per i contratti correnti:

GET /webadmin/api/content-contract
GET /webadmin/api/block-types
GET /webadmin/api/examples/contact-page

GET /webadmin/api/examples/contact-page mostra l'uso nativo di contact_form. Gli strumenti IA/operatore non devono indovinare gli handle né creare moduli di contatto con Trusted HTML, markup di form grezzo o link mailto: quando il blocco nativo Contact Form è disponibile.

L'applicazione dei contenuti resta orientata alla bozza e non pubblica per impostazione predefinita. Gli operatori devono validare i piani, applicarli solo dopo un'approvazione esplicita, visualizzare in anteprima la pagina in bozza e lasciare la pubblicazione a una persona o a un flusso di lavoro approvato esplicitamente.

Documentazione correlata

Privacy e tempistiche delle notifiche del sito (CMS 1.95.0)

In Siti → Modifica → Contatto, scegli il contenuto della notifica condivisa e la frequenza di consegna. I moduli di contatto e i plugin partecipanti, inclusa la Live Chat 0.7.0, ereditano questa politica. Ogni canale ha ancora il proprio interruttore di attivazione e la propria configurazione del destinatario. Un plugin non può sovrascrivere la scelta di solo avviso del sito.

  • full conserva notifiche dettagliate di contatti e chat, inclusi batch dettagliati.
  • alert_only invia una copia del sito attendibile, un conteggio dei messaggi e un collegamento alla casella di posta CMS autenticato. Sono esclusi i nomi dei visitatori, gli indirizzi e-mail, gli oggetti/corpi dei messaggi, gli URL di origine, gli indirizzi IP, i dettagli del browser, i referrer e i token di chat privata. Sono vietate le risposte dei visitatori, le intestazioni personalizzate e gli allegati.
  • immediate invia immediatamente ogni notifica idonea.
  • batched invia immediatamente la prima notifica di contatto, quindi combina ulteriori messaggi di contatto per lo stesso sito e destinatario dopo l'intervallo batch. La chat dal vivo si raggruppa in batch all'interno di ogni conversazione, quindi una nuova conversazione offline riceve immediatamente il primo avviso. L'intervallo predefinito è dieci minuti; l'intervallo supportato è compreso tra 1 e 60 minuti.
  • daily combina i canali idonei in un riepilogo giornaliero di solo conteggio per sito e destinatario. I riepiloghi giornalieri utilizzano sempre contenuti minimi, anche quando la modalità di notifica selezionata è full.

Lo switch separato daily_summary ricorda ai destinatari il lavoro ancora in sospeso nei giorni successivi. Con la consegna giornaliera e questa opzione disabilitata, solo i messaggi appena registrati producono una notifica giornaliera. I riepiloghi contano i messaggi non letti e quelli in attesa di risposta separatamente, con le etichette dei canali che distinguono i messaggi di contatto dalle conversazioni in chat. La lettura di un messaggio di contatto lo lascia in attesa di risposta; sono esclusi i record con risposta, archiviati, spam e in quarantena. La Live Chat utilizza l'ultimo mittente per determinare se una conversazione aperta attende una risposta da parte dell'operatore; la chiusura o la risposta lo rimuovono da quel conteggio. I canali esclusi non contribuiscono ai riepiloghi.

Per impostazione predefinita, i nuovi siti sono alert_only, batch di dieci minuti e un riepilogo giornaliero alle 09:00 nel fuso orario del sito. I siti esistenti mantengono full, consegna immediata e riepiloghi disabilitati durante l'aggiornamento. Abilita queste funzionalità esplicitamente sulle installazioni esistenti. La finestra giornaliera viene controllata una volta per giorno in sede: nessun lavoro in sospeso significa nessuna email e gli arrivi successivi rientrano nel riepilogo del giorno successivo.

Gli host devono eseguire lo scheduler di Laravel ogni minuto, ad esempio tramite la consueta voce cron php artisan schedule:run. Il pacchetto registra webblocks:notifications:dispatch ogni minuto; può anche essere invocato esplicitamente per la manutenzione. La posta in batch e quella giornaliera rimangono in sospeso mentre lo scheduler viene arrestato. Più lavoratori devono condividere una cache che supporta i blocchi atomici. I collegamenti di amministrazione utilizzano l'URL dell'applicazione attendibile; mantenere APP_URL configurato per l'host CMS. Non forniscono alcun bypass dell'accesso e applicano le normali autorizzazioni per account e sito.

Il pannello delle impostazioni del sito e l'API di notifica mostrano i risultati della consegna; la casella di posta dei contatti conserva lo stato di ogni invio. I risultati descrivono il trasferimento del trasporto, non la consegna garantita della posta in arrivo. Mail utilizza le impostazioni di posta personalizzate del CMS quando configurate, altrimenti le impostazioni di posta dell'ambiente. Le eccezioni SMTP e i payload dei messaggi non vengono copiati nei processi di recapito o nei dettagli degli errori. I tentativi di consegna non vengono ritentati automaticamente; i tentativi interrotti vengono contrassegnati come falliti dopo quindici minuti. La contabilità delle notifiche viene conservata per trenta giorni, separatamente dalla registrazione dei messaggi originari. I plugin disabilitati non vengono inviati; chiudendo una chat o disattivandola si annullano le notifiche in coda.

Questa funzione fornisce notifiche di messaggi e promemoria di lavori in sospeso. Non introduce il monitoraggio generale del tempo di attività del sito né invia risposte dell'operatore ai visitatori.

Integrità dello scheduler (CMS 1.95.1)

Il Dashboard e Siti → Modifica → Contatto mostrano lo stato registrato dello scheduler, l'ultimo heartbeat pianificato e l'ultima esecuzione di notifiche completata. L'API di notifica del sito restituisce lo stesso oggetto scheduler_health. Un'attività registrata o un'e-mail inviata immediatamente non confermano il funzionamento dello scheduler. La prova di esecuzione mancante è Non ancora verificata; le prove vecchie di più di cinque minuti sono Delayed. Vengono distinti gli errori di elaborazione e lo schema mancante e un'esecuzione live può mostrare brevemente In progress.

Quando la consegna in batch/giornaliera o i riepiloghi giornalieri sono abilitati, la pianificazione non verificata o ritardata produce un avviso evidente che le notifiche potrebbero rimanere in sospeso. L'amministratore del server o il provider di hosting possiede la configurazione una tantum; vedere Installazione. Il richiamo manuale del comando dispatch non crea un heartbeat pianificato. Un record di esecuzione integro non garantisce la consegna della posta in arrivo; continuare a rivedere i risultati di recapito per messaggio.