La WhatsApp Business Platform invia messaggi tramite la Cloud API (ospitata da Meta) o la legacy On-Premises API. I messaggi avviati dal business devono usare template pre-approvati in una categoria (marketing, utility, authentication); i messaggi di sessione in formato libero sono consentiti solo all'interno di una finestra di assistenza clienti di 24 ore aperta dall'ultimo messaggio dell'utente. L'opt-in è obbligatorio.
Cloud API vs On-Premises API
La WhatsApp Business Platform espone due API con lo stesso modello di messaggistica ma hosting differente. La Cloud API è ospitata da Meta: un business (o il suo solution provider) chiama un endpoint REST in stile Graph identificato da un phone-number ID, senza alcun client locale da gestire. La On-Premises API è un client containerizzato che il business ospita autonomamente, storicamente usato per motivi di residenza dei dati o latenza; Meta l'ha destinata alla dismissione a favore della Cloud API. Entrambe sono governate dalle stesse regole — template, finestra di 24 ore, categorie, qualità e opt-in — quindi la scelta è operativa (chi ospita) più che funzionale.
| Proprietà | Cloud API | On-Premises API |
|---|---|---|
| Hosting | Ospitato da Meta, nessun client da eseguire | Client containerizzato ospitato dall'azienda |
| Endpoint | Graph REST su un ID di numero di telefono | Endpoint REST del client locale |
| Aggiornamenti | Gestito da Meta | L'azienda gestisce le versioni client |
| Stato | Consigliato, in fase di sviluppo attivo | Destinato alla dismissione |
| Regole (modelli/finestra/qualità) | Identico | Identico |
Messaggi template (HSM) vs messaggi di sessione
WhatsApp separa le due direzioni della messaggistica business. Un business non può inviare a freddo a un utente contenuto in formato libero: qualsiasi messaggio avviato dal business deve essere un message template — storicamente chiamato Highly Structured Message (HSM) — che sia stato sottoposto a WhatsApp e approvato in anticipo, con segnaposto di variabili nominati e una categoria dichiarata. Una volta che l'utente risponde, si apre una finestra di assistenza clienti di 24 ore in cui il business può inviare messaggi di sessione in formato libero (testo, media, interattivi) senza template. Fuori da quella finestra, il business deve nuovamente iniziare con un template approvato. Questa regola template-first è il vincolo centrale della piattaforma.
POST https://graph.facebook.com/v20.0/{phone-number-id}/messages
Authorization: Bearer {access-token}
{
"messaging_product": "whatsapp",
"to": "15551234567",
"type": "template",
"template": {
"name": "order_shipped",
"language": { "code": "en_US" },
"components": [
{ "type": "body",
"parameters": [ { "type": "text", "text": "4021" } ] }
]
}
}La finestra di assistenza clienti di 24 ore
La finestra di 24 ore è il meccanismo che regola la messaggistica in formato libero. Si apre (o si riapre) ogni volta che l'utente invia un messaggio al business, e dura 24 ore dall'ultimo messaggio dell'utente. All'interno della finestra il business può rispondere con qualsiasi tipo di messaggio consentito — testo semplice, media, pulsanti interattivi o liste — senza usare un template. Quando la finestra si chiude, gli invii in formato libero vengono rifiutati e il business deve riprendere il contatto con un template approvato (soggetto a categoria e, per il marketing, a limiti per utente). Sia la tariffazione a sessione sia la più recente tariffazione per messaggio dipendono dal fatto che un invio ricada dentro o fuori questa finestra.
Categorie dei messaggi: marketing, utility, authentication
A ogni template è assegnata una categoria che governa come può essere usato e come viene tariffato. I template utility riguardano una transazione o un evento di account specifico e concordato (aggiornamenti d'ordine, promemoria di appuntamento, estratti conto). I template authentication consegnano codici monouso e verifiche, con un formato vincolato. I template marketing veicolano promozioni, offerte e re-engagement e sono i più strettamente governati — soggetti a opt-in dell'utente, segnali di qualità e limiti di frequenza. WhatsApp esamina il contenuto del template rispetto alla categoria dichiarata in fase di approvazione e può riclassificarlo; inviare contenuti marketing sotto un'etichetta utility è una causa comune di rifiuto o danno alla qualità.
| Categoria | Scopo | Note |
|---|---|---|
| Utility | Aggiornamenti delle transazioni/dell'account che l'utente si aspetta | Legato a un'azione o a un accordo specifici |
| Autenticazione | Codici monouso, verifica | Formato ristretto; focalizzato sull'OTP |
| Marketing | Promozioni, offerte, riattivazione | Opt-in rigoroso, governance di qualità e frequenza |
| Servizio (sessione) | Risposte in formato libero nella finestra di 24 ore | Nessun modello richiesto; non avviato dall'azienda |
Webhook: messaggi in ingresso e stato di consegna
La piattaforma è asincrona e guidata da callback. Un business configura un URL webhook a cui WhatsApp invia due tipi di eventi: messaggi in ingresso (le risposte dell'utente, media, tap sui pulsanti, posizione) e notifiche di stato per i messaggi in uscita, che progrediscono attraverso sent, delivered, read e — in caso di errore — failed con un codice di errore. Le conferme di lettura e il ciclo di vita del messaggio emergono qui, e l'arrivo di un evento di messaggio in ingresso è esattamente ciò che apre o aggiorna la finestra di 24 ore. Un'integrazione robusta conferma rapidamente i webhook e riconcilia lo stato di consegna con il proprio archivio messaggi, proprio come una piattaforma SMS riconcilia i DLR.
{
"entry": [{ "changes": [{ "value": {
"messaging_product": "whatsapp",
"messages": [{
"from": "15551234567", "id": "wamid.HBg...",
"timestamp": "1752796800",
"type": "text", "text": { "body": "Where is my order?" }
}]
} }] }]
}Qualità del numero, livelli e opt-in
Ogni numero di telefono business porta con sé una valutazione di qualità (mostrata come alta/media/bassa, spesso colorata verde/giallo/rosso) derivata da come gli utenti reagiscono ai suoi messaggi — blocchi e segnalazioni la abbassano. La qualità regola il livello del limite di messaggistica, che limita quanti utenti unici un numero può iniziare a contattare in una finestra mobile di 24 ore; i livelli salgono (per esempio 250, 1K, 10K, 100K, poi illimitato) man mano che qualità e volume si mantengono, e scendono se la qualità cala. Alla base di tutto c'è l'opt-in: WhatsApp richiede ai business di ottenere e registrare il consenso esplicito dell'utente, raccolto su qualsiasi canale, prima di inviare. Una cattiva prassi di opt-in emerge rapidamente come blocchi, qualità degradata e livello limitato.
| Signal | Significato | Effetto |
|---|---|---|
| Qualità: elevata (verde) | Pochi blocchi/segnalazioni | Idoneo a passare a livelli superiori |
| Qualità: media (giallo) | Alcuni commenti negativi | Sotto osservazione; scalabilità sospesa |
| Qualità: bassa (rosso) | Molti blocchi/report | Rischio di declassamento o segnalazione |
| Tier (250 / 1K / 10K / 100K / ∞) | Utenti unici avviati nelle 24 ore | Aumentato in base a qualità e volume costanti |
| Opt-in | Consenso dell'utente registrato | Richiesto prima di qualsiasi invio avviato dall'azienda |
Domande frequenti
Qual è la differenza tra la Cloud API e la On-Premises API?
Entrambe usano lo stesso modello di messaggistica WhatsApp, ma la Cloud API è ospitata da Meta (chiami un endpoint REST, niente da gestire), mentre la On-Premises API è un client containerizzato che ospiti tu. Meta ha destinato la On-Premises API alla dismissione a favore della Cloud API. Template, finestra di 24 ore, categorie e regole di qualità si applicano in modo identico a entrambe.
Che cos'è un message template (HSM) di WhatsApp?
Un template — storicamente un Highly Structured Message — è contenuto pre-approvato con segnaposto di variabili nominati e una categoria dichiarata. Qualsiasi messaggio WhatsApp avviato dal business deve essere un template; il contenuto in formato libero è consentito solo all'interno della finestra di assistenza clienti di 24 ore aperta da una risposta dell'utente.
Che cos'è la finestra di assistenza clienti di 24 ore?
È il periodo, della durata di 24 ore dall'ultimo messaggio dell'utente al business, durante il quale il business può inviare messaggi di sessione in formato libero senza template. Quando si chiude, gli invii in formato libero vengono rifiutati e il business deve riprendere il contatto usando un template approvato. Gli eventi webhook in ingresso aprono o aggiornano la finestra.
Quali sono le categorie dei messaggi WhatsApp?
I template sono categorizzati come utility (aggiornamenti di transazione/account attesi dall'utente), authentication (codici monouso e verifiche) o marketing (promozioni e re-engagement, i più strettamente governati). Le risposte in formato libero all'interno della finestra sono messaggi service. La categoria governa l'uso consentito e la tariffazione, e WhatsApp esamina il contenuto rispetto alla categoria dichiarata.
Cosa determina il limite di messaggistica di un numero WhatsApp?
Il livello di messaggistica limita quanti utenti unici un numero può iniziare a contattare per ogni finestra mobile di 24 ore (per esempio 250, 1K, 10K, 100K, poi illimitato). I livelli salgono con qualità e volume sostenuti e scendono se la qualità cala. La qualità è una valutazione alta/media/bassa guidata da blocchi e segnalazioni degli utenti.
Serve l'opt-in per messaggiare gli utenti su WhatsApp?
Sì. WhatsApp richiede un consenso esplicito e registrato dell'utente — che può essere raccolto su qualsiasi canale — prima che un business invii messaggi. Un opt-in debole emerge in fretta come blocchi e segnalazioni, che abbassano la valutazione di qualità del numero e possono limitare o degradare il suo livello di messaggistica.
Specifiche della fonte
Gli standard pubblicati su cui si basa questa pagina. Si apre in una nuova scheda.