Hai sistemato i tag Open Graph, hai incollato il link in una chat di WhatsApp per controllare e l’anteprima è ancora sbagliata: il titolo vecchio, senza immagine o senza nessuna card oltre all’URL nudo. È un modo classico di perdere mezz’ora, perché WhatsApp non ti dice quasi nulla su cosa ha visto o perché ha rinunciato.
Questo articolo copre tre cose: come WhatsApp costruisce quella piccola card di anteprima, il breve elenco di motivi per cui esce sbagliata e il trucco di un carattere che fa rileggere la pagina a WhatsApp invece di mostrarti una versione salvata e non aggiornata. Se preferisci andare dritto alla diagnosi, il debugger dell’anteprima dei link di WhatsApp scarica la tua pagina nello stesso modo in cui fa WhatsApp e ti dice cosa ha trovato.
Come WhatsApp costruisce l’anteprima di un link
Quando incolli un URL in una chat, il telefono non legge la pagina. Sono i server di WhatsApp a scaricarla, una volta, e a estrarre qualche tag dall’HTML per comporre la card: un titolo, una breve descrizione e un’immagine. Cerca prima i tag Open Graph (le righe `<meta property="og:...">` che una pagina mette nel suo `<head>`), passa ai tag di Twitter Card se mancano e, infine, all’elemento `<title>` quando non c’è altro.
I tre tag che contano di più sono `og:title`, `og:description` e `og:image`. Se quelli sono a posto, ottieni la card che ti aspetti. Ecco come si presenta un set completo:
<meta property="og:title" content="Il titolo della tua pagina"> <meta property="og:description" content="Un riassunto di una riga della pagina."> <meta property="og:image" content="https://esempio.com/preview.jpg">
Un dettaglio spiega quasi tutti i problemi che saltano fuori: a scaricare è un bot, non un browser. WhatsApp invia uno user agent da crawler, scarica l’HTML grezzo e si ferma lì. Non esegue JavaScript, non scorre e non aspetta che si carichi niente. Quello che c’è nell’HTML che il tuo server restituisce alla prima risposta è tutto ciò che WhatsApp arriverà a vedere.
I motivi più comuni per cui un’anteprima si rompe
La maggior parte delle anteprime rotte dipende da uno dei motivi qui sotto. Sono più o meno nell’ordine in cui conviene controllarli.
I tag non sono nell’HTML
Se la pagina non ha `og:title` né `og:image`, WhatsApp ha poco su cui lavorare. Può ripiegare sul `<title>` e mostrare una card semplice senza immagine, oppure non mostrare nulla oltre al link. Apri la pagina, guarda il codice sorgente e cerca `og:`. Se quelle righe non ci sono, non le ha viste nemmeno WhatsApp.
I tag vengono aggiunti da JavaScript
Questo è quello che frega i siti moderni. Se il tuo framework inserisce i meta tag dopo che la pagina si è caricata (una single-page application, o il rendering lato client), esistono nel browser ma non nell’HTML grezzo. WhatsApp non esegue quel JavaScript, quindi legge il guscio vuoto e non trova nulla. I tag devono stare nell’HTML che il server restituisce, prima che parta qualsiasi script. La soluzione è il rendering lato server o un passaggio di pre-rendering.
L’immagine è troppo piccola, troppo pesante o non è HTTPS
Per la card con immagine grande, `og:image` deve essere un’immagine vera, raggiungibile e di dimensioni ragionevoli. Sotto i 300×200 pixel circa, WhatsApp tende a passare a una miniatura piccola o a saltare l’immagine; un file molto grande (oltre i 5 MB circa) può essere scartato. L’URL dell’immagine deve essere https e deve caricarsi senza login. Un errore frequente: l’immagine è servita da un URL firmato di un CDN o di S3 con un token che scade, così l’anteprima funziona oggi e dà 404 la settimana prossima, quando il token muore.
La pagina blocca il crawler
Se la pagina è dietro un login, restituisce un 401 o un 403, o blocca gli user agent sconosciuti a livello di CDN, WhatsApp riceve un muro al posto del tuo HTML e non può comporre la card. Alcuni siti riservano i tag Open Graph a un bot di anteprima riconosciuto, ed è per questo che lo stesso URL può generare l’anteprima su una piattaforma e non su un’altra.
Il titolo o la descrizione sono troppo lunghi
Questo non blocca l’anteprima, la taglia soltanto. WhatsApp taglia il titolo dopo circa 65 caratteri e la descrizione dopo circa 160, così un titolo lungo viene troncato a metà frase. Metti le parole importanti all’inizio e tieni corto `og:title`.
La pagina è lenta o reindirizza troppo
Il crawler aspetta solo fino a un certo punto. Una pagina che impiega diversi secondi a rispondere, o una sepolta sotto una catena di reindirizzamenti, può andare in timeout prima che WhatsApp legga i tag. Punta il link all’URL finale e fai in modo che la prima risposta sia veloce.
Il trucco: fai sembrare nuovo l’URL
Ecco la parte che spiazza quasi tutti, e il motivo per cui un’anteprima resta sbagliata a lungo dopo che hai sistemato la pagina. WhatsApp mette in cache l’anteprima associata all’URL esatto. Una volta scaricata la tua pagina e composta la card, riusa quella card per lo stesso link e non scarica di nuovo per un bel po’. Così puoi correggere tutti i tag e il link che hai già condiviso continuerà a mostrare l’anteprima vecchia e rotta, perché WhatsApp non sta leggendo la tua pagina, sta leggendo la propria cache.
Il modo per aggirarlo è cambiare l’URL in modo che WhatsApp lo tratti come uno mai visto. Aggiungi un parametro di query che la tua pagina ignora:
https://esempio.com/la-tua-pagina → https://esempio.com/la-tua-pagina?v=2
Va bene qualsiasi parametro (`?v=2`, `?x=1`, `?refresh=1`), purché il testo dell’URL sia diverso da quello che WhatsApp ha già in cache. Vede un URL nuovo, scarica la pagina sul momento e legge i tuoi tag attuali. Se devi ricontrollare dopo un’altra modifica, alza il numero: `?v=3`, poi `?v=4`. La maggior parte delle pagine ignora un parametro di query sconosciuto, quindi questo non cambia nulla di ciò che vede il visitatore.
Una precisazione onesta. Questo ti dà un’anteprima funzionante da testare e da condividere d’ora in poi, ma non svuota la cache del tuo URL pulito originale. Quella voce scade secondo i tempi di WhatsApp, che Meta non pubblica e che possono arrivare a settimane. Quindi usa il parametro per confermare la correzione e per distribuire un link che oggi genera un’anteprima corretta, invece di aspettare che l’URL nudo si aggiorni da solo.
Guarda cosa vede WhatsApp, senza tirare a indovinare
Incollare un link in una chat vera più e più volte è un modo lento di fare debug, perché vedi solo il risultato, mai il motivo. Il debugger dell’anteprima dei link di WhatsApp fa lo scaricamento al posto tuo: richiede la tua pagina come il crawler di WhatsApp, mostra il titolo, la descrizione e l’immagine esatti che ha trovato e dà una lettura in linguaggio chiaro di cosa manca o cosa è troppo lungo. Quando mancano i tag Open Graph, scrive le righe `<meta>` da copiare, e ha un pulsante per bucare la cache che applica il trucco del parametro qui sopra. Controlla prima la pagina lì, sistema quello che segnala e poi condividi il link per davvero.
Domande frequenti
Perché WhatsApp mostra ancora l’anteprima vecchia dopo che ho sistemato la pagina?
WhatsApp ha messo in cache l’anteprima associata a quell’URL esatto e serve la card salvata invece di rileggere la tua pagina. Aggiungi un parametro di query (per esempio `?v=2`) perché scarichi di nuovo la pagina, oppure aspetta che la cache di WhatsApp scada da sola.
WhatsApp esegue JavaScript quando legge la mia pagina?
No. Il crawler di WhatsApp scarica l’HTML grezzo e si ferma. Se i tuoi tag Open Graph vengono aggiunti da JavaScript lato client, WhatsApp non li vede mai. I tag devono stare nell’HTML che il server restituisce, il che di solito significa rendering lato server o un passaggio di pre-rendering.
Perché non c’è l’immagine nella mia anteprima di WhatsApp?
Le cause più comuni sono un tag `og:image` mancante, un’immagine sotto i 300×200 pixel circa, un’immagine servita in http invece che in https, un’immagine dietro un login o con un URL firmato che scade, o un tag immagine aggiunto da JavaScript. Controlla l’immagine scelta con il debugger dell’anteprima dei link.
Per quanto tempo WhatsApp tiene in cache l’anteprima di un link?
Meta non pubblica la durata esatta e, in pratica, può durare settimane. Ecco perché non puoi contare sul fatto che la cache si svuoti da sola durante i test, ed ecco perché aggiungere un parametro di query è il modo affidabile di vedere un’anteprima nuova adesso.