WhatsApp Cloud API: come funziona e quanto costa davvero

WhatsApp Cloud API è l'interfaccia ufficiale con cui Meta permette a un software di inviare e ricevere messaggi WhatsApp da un numero aziendale, senza che nessun telefono resti acceso da qualche parte. È la strada ufficiale, e l'unica sensata per un'azienda: le librerie non ufficiali che pilotano WhatsApp Web funzionano finché non vengono rilevate, e allora l'account viene bloccato.

La differenza con un'integrazione qualsiasi sta in tre vincoli che non si possono aggirare: la finestra di 24 ore, i template preapprovati e la gestione dei media. Chi progetta un'automazione su WhatsApp senza tenerne conto costruisce qualcosa che si romperà in produzione.

Questo articolo spiega come funzionano nel concreto, con gli esempi presi dal caso studio dell'agente WhatsApp per affitti brevi realizzato per Rial Estate.

Come funziona: i tre pezzi da capire

L'architettura è più semplice di quanto sembri. Ci sono un numero, un insieme di template e due direzioni di traffico.

1. Il numero business. Un numero di telefono collegato a un account WhatsApp Business, verificato, non attivo su WhatsApp normale. È l'identità con cui l'azienda scrive.
2. L'invio. Il tuo software chiama l'interfaccia di Meta indicando destinatario e contenuto. Se sei fuori dalla finestra di 24 ore, il contenuto deve essere un template approvato con le sue variabili riempite.
3. La ricezione. Meta chiama un indirizzo web che indichi tu ogni volta che arriva un messaggio o cambia lo stato di uno inviato. È il canale da cui il tuo sistema scopre cosa succede.

Il pezzo che quasi tutti sottovalutano è il terzo. Ricevere è più importante che inviare: senza il canale di ricezione non sai se i tuoi messaggi arrivano, e non puoi rispondere a chi scrive.

La finestra di 24 ore: il vincolo che decide tutto

Questa è la regola da cui discende ogni scelta architetturale.

La logica di Meta è chiara: puoi conversare liberamente con chi ti ha appena scritto, ma non puoi contattare a freddo chi non ti ha cercato, se non con messaggi che Meta ha letto e approvato prima.

Come gestirlo nell'interfaccia dello staff

C'è un dettaglio di esperienza che vale la pena rubare. Nella casella condivisa costruita per il progetto, il campo di scrittura si disabilita da solo quando la finestra è chiusa, e mostra invece l'elenco dei template disponibili.

L'alternativa — lasciare scrivere e mostrare un errore dopo l'invio — è tecnicamente più semplice e molto peggiore: chi scrive perde il messaggio appena composto e non capisce perché. Rendere visibile il vincolo prima dell'azione, invece che dopo, è quasi sempre la scelta giusta.

I template: cosa sono e perché esistono

Un template è un messaggio con struttura fissa e variabili, che Meta approva prima dell'uso. Serve a impedire che le aziende usino WhatsApp per pubblicità non richiesta.

Un template ha tre parti: un'intestazione facoltativa (testo, immagine, documento), un corpo con variabili numerate, e un piè di pagina facoltativo. Le variabili le riempi al momento dell'invio: nome dell'ospite, data, importo.

Le regole per farli approvare senza perdere giorni sono raccolte in template WhatsApp Business: come farli approvare. Il punto da tenere a mente in fase di progetto è il tempo: l'approvazione non dipende da te e va messa in conto per ogni lingua che vuoi supportare, come spiegato in messaggi automatici multilingua.

Allegare documenti: due strade, due rischi diversi

Se il messaggio deve portare un PDF — istruzioni, ricevuta, modulo — ci sono due modi.

Nel progetto degli affitti brevi i PDF contenevano i codici di accesso ai portoni: la scelta è caduta sull'identificativo, accettando il lavoro ricorrente del rinnovo. È il tipo di decisione che va presa consapevolmente e scritta da qualche parte, perché fra sei mesi nessuno ricorderà perché esiste quello script.

Gli stati di consegna: il dato che quasi nessuno raccoglie

Ogni messaggio inviato genera aggiornamenti di stato: inviato, consegnato, letto, oppure fallito con un motivo. Meta li manda al tuo indirizzo di ricezione.

Raccoglierli costa poco e cambia molto. Senza, sai solo che il tuo sistema ha chiamato l'API senza errori — che non significa che il destinatario abbia ricevuto qualcosa. Con, puoi rispondere alla domanda che conta davvero: l'ospite ha letto le istruzioni?

Nella casella condivisa del progetto ogni messaggio automatico compare accanto alla conversazione con il suo stato. È stata la funzione che ha giustificato il software su misura, perché nessuno strumento pronto mostrava gli stati dei messaggi automatici dentro la chat — il ragionamento completo è in PWA su misura o software pronto.

Quanto costa davvero

Il modello di costo ha tre voci, e solo una dipende da WhatsApp.

• I template inviati. Si paga a messaggio, con tariffa che cambia per Paese di destinazione e per categoria (servizio, utilità, marketing). Meta aggiorna il listino periodicamente: verifica sempre la pagina ufficiale invece di fidarti di un numero letto in un articolo.
• Le risposte dentro la finestra di 24 ore. Non hanno costo per messaggio.
• L'infrastruttura. Il motore di automazione e l'hosting sono abbonamenti fissi, indipendenti dal volume dei messaggi.

Per dare un ordine di grandezza concreto: nel progetto degli affitti brevi, con 17 appartamenti e cinque tipi di messaggio, la spesa in messaggi è nell'ordine di poche decine di euro al mese. Non è la voce che pesa sul budget di un progetto del genere: pesa molto di più il lavoro di progettazione.

Esempi pratici

Un promemoria di appuntamento. Uno studio manda il promemoria 24 ore prima. È fuori dalla finestra, quindi serve un template con due variabili: nome e orario. Il paziente risponde "confermo": si apre la finestra, e da lì per 24 ore lo studio può scrivere liberamente.

Un ordine da confermare. Un e-commerce manda la conferma di spedizione con il codice di tracciamento. Se il cliente risponde chiedendo di cambiare indirizzo, la conversazione prosegue in testo libero. Lo schema è vicino a quello descritto in automazione customer care.

Un messaggio che fallisce. Il numero è sbagliato o non è su WhatsApp. Il tentativo produce uno stato "fallito" con un motivo. Se raccogli gli stati, lo staff lo vede e chiama; se non li raccogli, nessuno se ne accorge finché il cliente non si lamenta.

Errori da evitare

Usare librerie non ufficiali. Pilotare WhatsApp Web con strumenti non autorizzati funziona finché non viene rilevato. Poi l'account viene bloccato, e con lo stesso numero non si riparte. È una scorciatoia che costa il canale.

Progettare come se la finestra non esistesse. Costruire un flusso che manda testo libero a freddo significa costruire qualcosa che fallirà al primo invio reale.

Non raccogliere gli stati. È il dato più utile e il più ignorato. Costa un endpoint in più e ti dice se il tuo lavoro sta funzionando.

Ignorare l'errore per destinatario. In un invio massivo, un singolo destinatario in errore può fermare tutta la coda: gli invii successivi non partono. È uno degli errori che abbiamo pagato sul campo, raccontato in sei errori pagati sul campo.

Come applicarlo in azienda

Se stai valutando WhatsApp come canale automatizzato, le domande in ordine sono queste:

1. I tuoi messaggi partono a freddo o in risposta? Se partono a freddo, il progetto è fatto di template e devi mettere in conto i tempi di approvazione.
2. Chi presidia le risposte? Aprire un canale che nessuno legge peggiora il servizio. Serve una persona e un posto dove leggere.
3. Quali dati finiscono nei messaggi? Numeri di telefono e contenuti delle conversazioni sono dati personali: il tema è trattato in AI e GDPR.
4. Come colleghi il gestionale? È da lì che arrivano i dati che riempiono i template: vedi integrare il gestionale.

Se il canale WhatsApp ti interessa in ottica assistenza più che operativa, la panoramica è in automazione WhatsApp Business.

Conclusione

WhatsApp Cloud API non è complicata da usare: è vincolata. La finestra di 24 ore, i template da approvare e la gestione dei media non sono ostacoli da aggirare, sono la forma che il progetto deve prendere. Chi li accetta all'inizio costruisce qualcosa che regge; chi li scopre in corsa rifà il lavoro.

Le due cose da fare fin dal primo giorno: raccogliere gli stati di consegna, e decidere consapevolmente se i tuoi documenti possono stare su un indirizzo pubblico oppure no.

Se vuoi passare dai test con ChatGPT a un sistema AI integrato nei processi aziendali, Giallo Studio progetta agenti e automazioni su misura. Il progetto completo da cui vengono questi esempi è nel caso studio.

Schema consigliato: Article + FAQPage + BreadcrumbList