Modulo didattico · Sviluppo Web / E-commerce

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.

🏢
Meta Business Suite
Account aziendale
→
⚙️
App su Meta for Developers
Contenitore tecnico
→
💬
WABA
WhatsApp Business Account
→
📱
Numero verificato
Test o produzione
→
🔌
Cloud API
Invio/ricezione messaggi
01

Fondamenti

Prima di scrivere una sola riga di codice, è importante capire come è organizzata la piattaforma e quale terminologia useremo per tutto il modulo.

Piattaforma

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.

Differenza chiave

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.

Sicurezza

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.

Comunicazione

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.

Regola importante

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.

Contenuto

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.

02

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
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.

Errore comune: dimenticare che il token temporaneo scade dopo 24 ore. Se le richieste iniziano a fallire con errore 401, il primo sospetto è sempre un token scaduto.
03

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)

Risposte automatiche e gestione richieste in entrata
▾
Scenario: un cliente scrive "Vorrei sapere lo stato del mio ordine" e riceve subito una risposta automatica con un menu di opzioni.
Node.js — risposta al webhook in entrata
// 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);
});
Cosa non fare: non rispondere solo con testo libero se il flusso richiede scelte precise — usare bottoni riduce errori di digitazione e accelera la gestione.
📦

Notifiche transazionali

Conferme d'ordine, promemoria appuntamenti
▾
Scenario: un e-commerce conferma automaticamente un ordine appena pagato, usando un template già approvato da Meta.
cURL — invio di un template approvato
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" }] }]
    }
  }'
Cosa non fare: non provare a inviare un messaggio di testo libero fuori dalla finestra delle 24 ore: verrà rifiutato. Serve sempre un template approvato.
📣

Marketing e broadcast

Campagne promozionali con consenso esplicito
▾
Scenario: un negozio invia un template promozionale a una lista di clienti che hanno dato consenso (opt-in) a ricevere comunicazioni.
Node.js — invio broadcast a una lista
// 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
}
Cosa non fare: non inviare mai messaggi promozionali senza un consenso esplicito e verificabile: viola le policy di Meta e può portare alla sospensione del numero.
🤖

Chatbot conversazionale

Flusso decisionale con bottoni e liste interattive
▾
Scenario: uno studio professionale guida l'utente attraverso una serie di domande per raccogliere informazioni prima di fissare un appuntamento.
Node.js — macchina a stati semplificata
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!';
}
Cosa non fare: non costruire flussi troppo rigidi senza una via di uscita verso un operatore umano: previeni sempre la possibilità di "parlare con una persona".
🛒

E-commerce integrato

Catalogo prodotti e carrello via WhatsApp
▾
Scenario: un negozio collega il proprio catalogo Meta Commerce e permette al cliente di sfogliare i prodotti e aggiungerli al carrello direttamente in chat.
cURL — invio messaggio con prodotto singolo
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}"
      }
    }
  }'
Cosa non fare: non dimenticare di collegare il catalogo su Meta Commerce Manager prima di testare: senza catalogo attivo, l'API restituirà un errore di riferimento non trovato.
04

Glossario interattivo

Clicca su un termine per rivelarne la definizione. Utile per un ripasso rapido prima delle esercitazioni.

WABA clicca
WhatsApp Business Account: l'entità che raggruppa uno o più numeri di telefono usati per la messaggistica aziendale.
Token clicca
Stringa segreta usata per autenticare ogni chiamata all'API. Va sempre custodita e mai esposta lato client.
Webhook clicca
Endpoint del tuo server che Meta chiama automaticamente per notificare eventi come messaggi in arrivo o stati di consegna.
Template clicca
Messaggio predefinito, sottoposto e approvato da Meta, utilizzabile anche fuori dalla finestra di 24 ore.
Finestra 24h clicca
Periodo entro cui puoi rispondere liberamente a un utente dopo il suo ultimo messaggio, senza dover usare un template.
Phone Number ID clicca
Identificativo univoco assegnato da Meta al numero di telefono collegato alla tua WABA, usato in ogni chiamata API.
System User clicca
Utente tecnico non legato a una persona fisica, usato per generare token di accesso permanenti in produzione.
Opt-in clicca
Consenso esplicito dato dall'utente a ricevere comunicazioni, obbligatorio per messaggi di marketing.
05

Esercitazioni pratiche

Verifica quanto hai appreso con questo breve quiz di autovalutazione, poi prova il mini-progetto guidato.

1. Fuori dalla finestra di 24 ore, come puoi scrivere a un utente?
2. Qual è la differenza principale tra token temporaneo e permanente?
3. A cosa serve il webhook?
4. Perché una campagna marketing richiede l'opt-in?

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

06

Attestato di completamento

Una volta completati tutti i passaggi del setup operativo (Sezione 2), potrai generare il tuo attestato personale in PDF.

🔒
Attestato non ancora disponibile
Completa tutti e 5 i passaggi della Sezione 2 — Setup operativo — per sbloccarlo.