Plugin prenotazioni WordPress: come ho sostituito Calendly con un blocco

Faccio tante cose per i clienti che poi non racconto a nessuno: plugin, integrazioni, automazioni che risolvono un problema preciso e restano chiusi in un repository, casi d’uso che conosco solo io. Eppure, una volta fatte, possono servire ad altri, sia a chi ha lo stesso problema sia a chi cerca qualcuno che i plugin su misura li sappia fare. Così inauguro una serie, e comincio con il caso in cui il cliente ero io: un plugin prenotazioni WordPress che ha preso il posto di Calendly nella pagina con cui le persone prenotano una chiacchierata con me.

In questo articolo ti racconto perché non mi bastavano Calendly e TidyCal, come funziona il blocco Gutenberg che vedi su questa pagina e quali problemi ho dovuto risolvere strada facendo: fusi orari e ora legale, doppie prenotazioni, Google Calendar senza librerie, email con l’invito in allegato, promemoria, un webhook firmato verso n8n. Il codice è pubblico su GitHub, quindi se vuoi puoi installarlo, leggerlo o smontarlo pezzo per pezzo.

Faccio cose, vedo gente

Una serie di articoli sui plugin WordPress fatti su misura per i clienti: il problema di partenza, le scelte tecniche, cosa ha funzionato e cosa manca ancora. Questa è la prima puntata.

Il titolo lo rubo a Nanni Moretti in Ecce Bombo: «Faccio cose, vedo gente». Mi è sempre sembrata la descrizione più sincera del mio lavoro, perché una buona parte delle giornate la passo davvero a fare cose per gente che ha un problema concreto, e quasi mai quelle cose finiscono scritte da qualche parte. Il cliente è contento, il plugin gira, io passo al prossimo, e il ragionamento che ci stava dietro evapora.

Da qui l’idea della serie: ogni puntata racconta un plugin WordPress su misura, con un’analisi del problema di partenza, l’architettura, i bug e qualche screenshot per farti vedere i risultati.

Se hai lo stesso problema o le stesse esigenze troverai abbastanza dettagli per capire se fa per te, e se cerchi qualcuno che te la costruisca saprai come lavoro.

Nelle prossime puntate parlerò di un convertitore da WPBakery a Gutenberg per una scuola di formazione, di un sistema di listini per cliente e di un multi magazzino su WooCommerce per un e-commerce B2B. Ma si parte da casa mia, perché il primo plugin prenotazioni WordPress della serie l’ho scritto per il mio stesso blog.

Un plugin prenotazioni al posto di Calendly

Calendly e TidyCal funzionano benissimo, ma i dati delle persone stanno sui loro server, il widget è una loro pagina e ogni dettaglio in più costa un piano superiore. Volevo un plugin prenotazioni tutto dentro WordPress.

Per anni ho consigliato Calendly o TidyCal per far prenotare le call conoscitive, e per anni mi sono detto «mannaggia, un altro servizio esterno».

Il modulo era un iframe dentro il mio sito, con i colori di qualcun altro. I nomi e le email delle persone finivano in un account che non era il mio sito, e la mia informativa privacy doveva spiegare un trattamento in più. Il collegamento con Google Calendar e Meet c’era, ma ogni funzione in più, dai promemoria alle domande personalizzate ai webhook, viveva in un piano a pagamento.

A inizio ottobre, mentre sistemavo il blog per il prossimo WordCamp, mi sono chiesto quanto sarebbe costato farmi un plugin prenotazioni WordPress mio: un blocco Gutenberg da mettere in una pagina, un calendario con gli orari liberi, la conferma via email con l’invito per il calendario, e l’integrazione con Google per Meet e per gli orari già occupati. Pensavo fosse un lavorone. Invece, lavorando con Claud.ia come racconto più avanti, la prima versione funzionante è arrivata nel giro di poco e le funzioni che mi mancavano sono entrate una release alla volta.

I requisiti che mi ero scritto erano pochi e chiari. Nessun servizio esterno obbligatorio: il plugin deve funzionare con le email di WordPress e senza Google, e usare Google e Resend solo se li configuri. Dati sul mio database, con gli strumenti privacy di WordPress per esportare e cancellare. Zero doppie prenotazioni, anche quando due persone cliccano lo stesso orario nello stesso secondo. E un aspetto del widget che non facesse rimpiangere Calendly, perché le persone che prenotano una call conoscitiva stanno decidendo se fidarsi di te, e un calendario brutto non aiuta.

Scegliere giorno ed orario

Il blocco del plugin prenotazioni mostra due mesi affiancati, gli orari liberi del giorno scelto nel fuso del visitatore e, con colori diversi, i giorni pieni, le chiusure e le festività italiane. Il clic su un orario apre una modale con il modulo.

Il blocco si chiama wpbac/booking ed è un blocco dinamico: il file render.php stampa un contenitore con la configurazione del tipo di call e un’app React, caricata come viewScript, disegna il calendario. Ho scelto due mesi affiancati perché è il formato con cui la gente ragiona quando cerca una data («la settimana prossima no, quella dopo forse»), e su schermi stretti il secondo mese sparisce da solo. Gli orari del giorno scelto compaiono a destra, in due colonne, e il clic apre una modale accessibile con nome, email, le domande personalizzate del tipo di call e la casella del consenso privacy.

La parte che sembra banale e non lo è si chiama fuso orario. Nel database salvo tutto come timestamp UNIX in UTC; gli orari settimanali dei tipi di call sono nel fuso del sito, wp_timezone(); il visitatore vede gli slot nel suo fuso, che può cambiare da un selettore. Il generatore degli slot costruisce un giorno locale alla volta, così l’ora legale la gestisce il fuso e non un conto fatto a mano, e quando il fuso del cliente è diverso da quello del sito la mia email di avviso riporta entrambi gli orari. Ho sbagliato questa cosa abbastanza volte in passato da scrivere subito i test, prima ancora dell’interfaccia.

Ogni tipo di call ha durata, intervallo tra gli slot, pause prima e dopo, preavviso minimo e orizzonte massimo, un luogo (Meet o altro) e un elenco di domande. Le pause sono importanti: una prenotazione occupa anche i minuti di pausa del proprio tipo di call, così non mi ritrovo due chiacchierate attaccate senza il tempo di prendere un caffè. Dalle impostazioni si fissano un massimo di call al giorno e la regola di una sola call attiva per cliente: chi ha già una prenotazione in piedi non può farne una seconda finché la prima non è passata o annullata.

Poi ci sono i giorni in cui non si prenota. Le eccezioni si bloccano da un calendario nell’admin, con un clic su un giorno e Maiusc più clic su un intervallo, per tutti i tipi di call o per uno solo. Le festività italiane si chiudono da sole, Pasqua e Lunedì dell’Angelo compresi: la data di Pasqua la calcolo con l’algoritmo di Gauss invece di usare la funzione easter_date() di PHP, che dipende da un’estensione non sempre installata sugli hosting.

Nel widget i giorni pieni sono ambra, le chiusure rosse, le festività viola con il nome al passaggio del mouse, e gli orari già presi restano visibili con un lucchetto. Sembra un dettaglio estetico, ma un giorno che pare vuoto e non si può cliccare è una delle cose più frustranti di un plugin prenotazioni, e la legenda sotto il calendario toglie ogni dubbio.

Google Calendar senza SDK

L’integrazione con Google Calendar usa OAuth2 con un client tuo e le API REST chiamate con wp_remote_post, senza la libreria ufficiale: crea l’evento, genera il link Meet e legge gli orari occupati.

La libreria PHP di Google pesa decine di megabyte e porta con sé una catena di dipendenze che in un plugin WordPress non voglio: conflitti di versione con altri plugin, autoload pesanti, aggiornamenti di sicurezza da inseguire. Le chiamate che mi servono sono quattro, e le API di Google Calendar sono REST con JSON. Così la classe CalendarClient parla con l’endpoint calendar/v3 usando wp_remote_get e wp_remote_post, e la classe OAuthClient gestisce il consenso, lo scambio del codice e il rinnovo del token di accesso.

La configurazione richiede un client OAuth di tipo «Applicazione web» creato nella Google Cloud Console, con l’URI di reindirizzamento che il plugin mostra nelle impostazioni; l’admin contiene una guida passo passo, nata dopo che io stesso ho sbagliato tipo di client la prima volta (quello «Desktop» accetta solo redirect su localhost). Il refresh token finisce nel database cifrato con libsodium, con una chiave derivata dai salt di WordPress, così un dump del database senza il file di configurazione non serve a nulla.

Quando arriva una prenotazione il plugin crea l’evento sul calendario, con il cliente tra gli invitati e la richiesta di una stanza Google Meet, e salva l’id dell’evento per poterlo spostare o cancellare. Per gli orari occupati all’inizio usavo l’endpoint freeBusy, che restituisce gli intervalli pieni di un calendario: semplice, veloce, e sbagliato per il mio caso. Il perché lo racconto nella sezione sulle cose che mancano, perché è una storia che merita il suo spazio.

Un dettaglio che risparmia chiamate: la disponibilità, con il free/busy già incorporato, resta in un transient di cinque minuti, e la chiave della cache include il valore dell’opzione sugli eventi tutto il giorno, così cambiando l’impostazione non si vedono dati vecchi. Un altro dettaglio che risparmia telefonate dagli amici: nelle impostazioni si può chiedere a Google di mettere un promemoria sul calendario dell’organizzatore, perché il cliente riceve i suoi via email ma io, se non suona qualcosa, me ne dimentico.

Niente doppie prenotazioni

Due persone che scelgono lo stesso orario nello stesso istante non devono poterlo prenotare entrambe: un lock sul database, un secondo controllo di disponibilità dentro il lock e un inserimento in try/finally. Senza nonce, di proposito.

Il problema classico di ogni plugin prenotazioni è la corsa: il visitatore A e il visitatore B vedono lo stesso slot libero, cliccano insieme, e il controllo «è ancora libero?» risponde sì a tutti e due. La soluzione nel plugin passa da GET_LOCK di MySQL: prima di scrivere, il repository acquisisce un lock con nome, rifà il controllo di disponibilità dentro il lock, inserisce la riga e rilascia il lock in un try/finally, così anche un’eccezione non lascia la porta chiusa.

Anche la regola di una sola call per cliente vive dentro il lock, e il messaggio di errore non dice né data né ora della prenotazione esistente, per non rivelare a uno sconosciuto quando una certa email ha un appuntamento.

La seconda scelta controintuitiva riguarda il nonce. Gli endpoint pubblici del plugin, quelli per leggere gli slot e creare o gestire una prenotazione, non usano il nonce di WordPress. Il motivo è la cache di pagina: su un sito con LiteSpeed Cache, come il mio, l’HTML della pagina resta in cache per ore, e un nonce stampato dentro scade nel giro di mezza giornata; chi arriva dopo trova un modulo che non invia.

La protezione è affidata ad altro: un campo honeypot invisibile, un tempo minimo di compilazione di due secondi, un tetto alle richieste per IP tenuto nei transient (cinque prenotazioni l’ora e trenta operazioni di gestione ogni dieci minuti), e il consenso privacy obbligatorio.

Il link con cui il cliente annulla o sposta la call contiene un token derivato: un HMAC calcolato dall’id della prenotazione con i salt di WordPress. Non lo salvo in chiaro da nessuna parte e posso ricalcolarlo quando serve, per esempio per metterlo nei promemoria. L’indirizzo IP, che serve solo a contare le richieste, è salvato come hash. E le risposte REST escono con Cache-Control: no-store e l’equivalente per LiteSpeed, perché la cosa peggiore che possa fare una cache è servire a qualcuno gli slot liberi di un’ora fa.

Email, Resend e promemoria

Ogni prenotazione produce due email con l’invito iCal in allegato e messaggi personalizzabili con i segnaposto; con una chiave Resend le email e i promemoria sono programmati sul loro servizio, altrimenti ci pensano wp_mail e WP-Cron.

Alla conferma partono due email: a me, con le risposte alle domande e, se i fusi sono diversi, l’orario anche nel fuso del sito, e al cliente, con il messaggio di ringraziamento, il link per spostare o annullare e un file .ics in allegato. L’invito lo costruisce una piccola classe che rispetta la RFC 5545, con il folding delle righe a 75 ottetti che sembra una pignoleria e invece decide se Outlook apre l’allegato o lo ignora. I testi di conferma, spostamento e annullamento si modificano dall’admin con segnaposto come {name}, {date}, {time}, {manage_url}, e i template HTML si possono sovrascrivere dal tema.

Le email di WordPress, però, hanno un problema noto: partono dal server con wp_mail e spesso finiscono in spam, e i promemoria dipendono da WP-Cron, che si sveglia solo quando qualcuno visita il sito. Per questo ho aggiunto Resend come canale opzionale: con la chiave API le email partono dal loro servizio, con il dominio autenticato via SPF e DKIM, e i promemoria del giorno prima e dell’ora prima vengono programmati con scheduled_at nel momento stesso della prenotazione, e aggiornati o cancellati se la call viene spostata o annullata.

Il punto delicato è il fallback. Se Resend risponde con un errore, anche solo nella email di prova, il plugin lo disattiva da solo, torna a wp_mail e WP-Cron, avvisa il proprietario con una email e mostra in admin tutti i dati del tentativo con un pulsante «Copia»: mittente e sua origine, destinatari, chiave mascherata, risposta HTTP.

Se la chiave è di tipo «solo invio» e non può cancellare le email programmate, i promemoria restano su cron, perché un promemoria per una call che hai spostato è peggio di nessun promemoria. E WP-Cron gira comunque ogni quindici minuti come rete di sicurezza, con l’ultimo passaggio visibile nella scheda Notifiche, così se il cron è fermo lo vedi prima dei tuoi clienti.

Un webhook per n8n

A ogni prenotazione creata, spostata o annullata il plugin manda un POST JSON firmato con HMAC SHA-256 all’URL che vuoi: nel mio caso un nodo Webhook di n8n che aggiorna il CRM e mi scrive su Telegram.

Un plugin prenotazioni WordPress che tiene i dati in casa deve anche saperli far uscire, altrimenti l’agenda diventa un’isola. Il modo più semplice e più robusto è un webhook: per gli eventi booking.created, booking.rescheduled e booking.cancelled il plugin invia un POST con tutti i dati della prenotazione, dal link di gestione alla pagina di origine, dall’id dell’evento Google alle date di creazione e annullamento, alla descrizione del tipo di call. Nelle impostazioni c’è un esempio del JSON e un pulsante di prova.

La richiesta porta l’header X-Wpbac-Signature con l’HMAC SHA-256 del corpo calcolato con un segreto che scegli tu, così il ricevente può scartare le chiamate che non vengono dal tuo sito. L’invio non blocca la prenotazione: se n8n è giù, il cliente riceve comunque la conferma e io trovo l’errore nel log. Dall’altra parte ho un workflow n8n che riceve l’evento, aggiunge il contatto al CRM, mi manda una notifica su Telegram e prepara una nota con le risposte alle domande, lo stesso schema che uso per altre automazioni.

Gli stessi tre momenti sono esposti anche come azioni WordPress (wpbac_booking_created e sorelle), per chi preferisce agganciarsi con un po’ di PHP invece che con un webhook, e l’elenco delle prenotazioni si esporta in CSV con il punto e virgola, l’UTF-8 e la protezione dalle formule, perché un nome che inizia con un uguale non deve diventare una macro quando il file si apre in Excel.

Claud.ia scrive, PHPStan controlla

PHP 8.3 con tipi stretti, PSR-4, logica di dominio in classi pure coperte da PHPUnit, PHPStan a livello 6, WPCS, una CI su GitHub che costruisce la release e gli aggiornamenti automatici dalle release stesse.

Il plugin l’ho costruito insieme a Claud.ia, la mia versione personalizzata di Claude Code, con il metodo che descrivo nella guida a Claude Code: un file CLAUDE.md con le regole del progetto, requisiti scritti prima del codice, e la frase che chiude ogni richiesta, «chiedi se hai domande e proponi miglioramenti». Molte delle cose che hai letto, dal lock al folding dell’ICS, sono nate da una sua domanda a cui ho risposto «sì, bravo, fallo».

L’architettura è quella che chiamo nucleo puro più adattatori. La logica che decide quali slot sono liberi, come si uniscono gli intervalli delle eccezioni, quando cadono le festività, come si costruisce l’ICS o il CSV, come si pianificano i promemoria, vive in classi senza WordPress dentro, testate con PHPUnit. Tutto ciò che tocca il database, Google, Resend o le REST API sta in classi separate, iniettate dal costruttore. Il risultato è un plugin prenotazioni con una settantina di test che girano in pochi secondi e che mi hanno già salvato dal rompere la gestione dell’ora legale mentre aggiungevo il massimo di call al giorno.

La qualità la controlla una CI su GitHub Actions: a ogni push partono phpcs con gli standard WordPress, PHPStan a livello 6, PHPUnit, la build dei blocchi e uno script che verifica che i file compilati citati nel PHP esistano davvero (un classico: il PHP carica build/view.js e nello zip non c’è). La release è un comando, npm run release:minor, che aggiorna la versione in quattro file, crea tag e push, e aspetta che il workflow pubblichi lo zip. Da lì il plugin si aggiorna da solo sui siti dove è installato, con plugin-update-checker agganciato alle release di GitHub, e una scheda Aggiornamenti per installare la nuova versione con un clic.

Per questo il repository è pubblico: non solo per farti leggere il codice, ma perché gli aggiornamenti automatici lo richiedono. Se il blog è uno dei posti in cui provo le cose prima di proporle ai clienti, il plugin prenotazioni WordPress è il caso in cui tutta la catena di strumenti attorno all’AI, dai test alla CI, ha fatto la differenza tra un esperimento e una cosa che uso davvero.

Cosa manca ancora

Il bug dei compleanni che bloccavano la giornata, le funzioni che non ho ancora scritto e le cose che non scriverò: pagamenti, più organizzatori, un’app per il telefono.

La storia promessa. Per qualche giorno il calendario mostrava interi giorni pieni senza motivo. Nessuna prenotazione, nessuna eccezione, eppure ambra. Il colpevole era il free/busy di Google: l’endpoint considera occupato anche un evento che dura tutto il giorno, e sul mio calendario i compleanni degli amici e i promemoria sono eventi di quel tipo. Risultato: il compleanno di mia cugina chiudeva l’agenda. La correzione, nella versione 0.8.1, legge l’elenco degli eventi invece del free/busy e scarta quelli tutto il giorno, quelli segnati «libero», gli annullati e gli inviti rifiutati, con una funzione pura e testata su cui ho scritto il test prima della correzione, come insegnano i libri.

Cosa manca ancora, in ordine di probabilità che lo faccia: la traduzione (il plugin oggi parla solo italiano, e per il mio sito va bene), la possibilità di avere più organizzatori con calendari diversi, e un selettore di calendario per chi ne ha più di uno sullo stesso account Google. Cosa non farò: i pagamenti, perché per quelli ci sono WooCommerce e i plugin di booking seri, e un’app, perché la scheda Prenotazioni funziona già bene dal telefono.

Faccio ancora un disclaimer: il plugin non è pensato per sostituire un gestionale di appuntamenti con decine di operatori e risorse. È un plugin prenotazioni WordPress per professionisti che vogliono una call conoscitiva prenotabile dal proprio sito, con i dati a casa propria e Google Meet pronto. Per quel caso, che è il mio e quello di parecchi clienti, fa tutto quello che facevano Calendly e TidyCal, e qualche cosa in più.

Domande frequenti

La call è prenotata, il resto lo fa il cron

Un calendario nel proprio sito, i dati nel proprio database e le integrazioni che servono davvero: questo plugin prenotazioni WordPress fa il lavoro di Calendly senza farmi uscire da WordPress.

Sono partito con l’idea di togliere un iframe dal sito e sono arrivato con un plugin prenotazioni WordPress che gestisce fusi orari, festività, Google Meet, email con l’invito, promemoria e webhook, con i test e la CI che ogni plugin serio dovrebbe avere. La lezione che mi porto a casa, e che vale per tutta la serie, è che i problemi interessanti non stavano nel calendario ma attorno: la corsa tra due prenotazioni, la cache che si mangia il nonce, il compleanno che chiude l’agenda. Sono le cose che non si vedono nella demo di un prodotto e che si scoprono solo facendo.

Se vuoi approfondire, il repository su GitHub ha un README con la configurazione di Google e di Resend e un CHANGELOG che racconta l’evoluzione versione per versione; la guida a Claude Code spiega il metodo con cui l’ho scritto insieme a Claud.ia; e nella categoria WordPress troverai le prossime puntate della serie. Se invece hai un sito e vuoi una cosa simile, o diversa, cucita sul tuo lavoro, la prova del nove è semplice: prenota una call dal plugin stesso, e vediamo insieme cosa ti serve.

Adesso tocca a te: che cosa ti manca nei moduli di prenotazione che hai usato finora, e che cosa ti ha fatto chiudere la scheda? Scrivilo nei commenti. E se conosci un consulente che ancora manda i link di Calendly con il logo di qualcun altro, girargli questo articolo è un gesto di affetto.