Creare applicazioni su WhatsApp Business Platform
Un percorso operativo, pensato per chi si avvicina per la prima volta alle API di Meta: dai concetti di base alla configurazione, fino a cinque casi d'uso reali con esempi di codice commentati.
Fondamenti
Prima di scrivere una sola riga di codice, è importante capire come è organizzata la piattaforma e quale terminologia useremo per tutto il modulo.
WhatsApp Business Platform
È l'infrastruttura di Meta pensata per le aziende: permette di inviare e ricevere messaggi in modo automatizzato, tramite la Cloud API, senza dover gestire server proprietari.
Cloud API vs App Business
L'app WhatsApp Business (quella che si usa dal telefono) è per la gestione manuale. La Cloud API è invece pensata per l'integrazione con software: è quella che useremo in questo modulo.
Token di accesso
Ogni richiesta all'API deve essere autenticata con un token. Esiste un token temporaneo (24h, per i test) e un token permanente legato a un System User, da usare in produzione.
Webhook
È l'URL del tuo server che Meta contatta automaticamente ogni volta che arriva un messaggio, una risposta a un bottone o un aggiornamento di stato.
Finestra di 24 ore
Puoi rispondere liberamente a un utente solo entro 24 ore dal suo ultimo messaggio. Fuori da questa finestra, puoi scrivere solo usando template approvati da Meta.
Template di messaggio
Sono messaggi predefiniti (es. conferma d'ordine) che devono essere sottoposti e approvati da Meta prima di poter essere inviati fuori dalla finestra delle 24 ore.
Setup operativo passo-passo
Segui questi cinque passaggi in ordine. Spunta ogni step man mano che lo completi: la barra di avanzamento nella barra laterale si aggiornerà automaticamente.
01Crea un account Meta Business Suite
Vai su business.facebook.com e crea (o collega) l'account aziendale della tua attività didattica o del progetto esercitazione. Questo account sarà il "contenitore" di tutte le risorse Meta.
02Crea un'app su Meta for Developers
Su developers.facebook.com, crea una nuova app di tipo "Business" e aggiungi il prodotto WhatsApp. Meta ti assegnerà automaticamente un numero di test gratuito.
03Genera il token di accesso temporaneo
Dalla dashboard "WhatsApp > Configurazione API" copia il token temporaneo (valido 24h) e il Phone Number ID: ti serviranno per la prima chiamata di prova.
04Invia il tuo primo messaggio di prova
Aggiungi come destinatario di test il tuo numero personale (verificato via SMS), poi esegui questa richiesta sostituendo i segnaposto:
curl -X POST \ 'https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages' \ -H 'Authorization: Bearer {TOKEN_TEMPORANEO}' \ -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "to": "{NUMERO_DESTINATARIO}", "type": "text", "text": { "body": "Ciao! Questo è il mio primo messaggio via Cloud API." } }'Segna come completato quando ricevi il messaggio sul telefono
05Configura il webhook di ricezione
Nella sezione "Webhook" dell'app, imposta un URL pubblico (in fase di apprendimento puoi usare un tunnel come ngrok) e un "verify token" a tua scelta. Da questo momento il tuo server riceverà ogni messaggio in arrivo.
Le cinque tipologie di applicazione
Ogni tipologia risponde a un bisogno diverso. Clicca su ciascuna scheda per aprire scenario, flusso ed esempio di codice.
Assistenza clienti (customer care)
// Riceviamo il messaggio dal webhook e rispondiamo con un menu app.post('/webhook', async (req, res) => { const msg = req.body.entry[0].changes[0].value.messages?.[0]; if (msg) { await inviaMessaggio(msg.from, { type: 'interactive', interactive: { type: 'button', body: { text: 'Come possiamo aiutarti?' }, action: { buttons: [ { type:'reply', reply:{ id:'ordine', title:'Stato ordine' } }, { type:'reply', reply:{ id:'assistenza', title:'Parla con operatore' } } ]} } }); } res.sendStatus(200); });
Notifiche transazionali
curl -X POST \ 'https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages' \ -H 'Authorization: Bearer {TOKEN}' -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "to": "{NUMERO_CLIENTE}", "type": "template", "template": { "name": "conferma_ordine", "language": { "code": "it" }, "components": [{ "type":"body", "parameters": [{ "type":"text", "text":"12345" }] }] } }'
Marketing e broadcast
// Cicliamo su una lista di numeri con opt-in verificato const destinatari = await getClientiConOptIn(); for (const numero of destinatari) { await inviaTemplate(numero, 'promo_stagionale', ['15%']); await attendi(200); // rispettare i limiti di invio }
Chatbot conversazionale
const stati = { INIZIO: { messaggio: 'Che servizio ti interessa?', prossimo: 'SERVIZIO' }, SERVIZIO: { messaggio: 'In che data preferisci?', prossimo: 'DATA' }, DATA: { messaggio: 'Perfetto, ti confermiamo a breve!', prossimo: 'FINE' } }; function gestisciRisposta(sessione, testoUtente) { const statoCorrente = stati[sessione.stato]; sessione.stato = statoCorrente.prossimo; return stati[sessione.stato]?.messaggio ?? 'Grazie, a presto!'; }
E-commerce integrato
curl -X POST \ 'https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages' \ -H 'Authorization: Bearer {TOKEN}' -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "to": "{NUMERO_CLIENTE}", "type": "interactive", "interactive": { "type": "product", "body": { "text": "Ecco il prodotto che cercavi:" }, "action": { "catalog_id": "{CATALOG_ID}", "product_retailer_id": "{SKU_PRODOTTO}" } } }'
Glossario interattivo
Clicca su un termine per rivelarne la definizione. Utile per un ripasso rapido prima delle esercitazioni.
Esercitazioni pratiche
Verifica quanto hai appreso con questo breve quiz di autovalutazione, poi prova il mini-progetto guidato.
Mini-progetto guidato: il tuo primo webhook di prova
Metti in pratica quanto visto finora completando questi passaggi in autonomia. Non è richiesto codice avanzato: l'obiettivo è vedere l'intero flusso funzionare end-to-end.
Crea un piccolo server Node.js con Express che risponda su /webhook
Esponi il server con un tunnel temporaneo (es. ngrok) e collega l'URL nel pannello Meta
Invia un messaggio al tuo numero di test e verifica che il webhook lo stampi in console
Rispondi automaticamente con un messaggio di conferma, riutilizzando il codice della Sezione 3
Attestato di completamento
Una volta completati tutti i passaggi del setup operativo (Sezione 2), potrai generare il tuo attestato personale in PDF.