WhatsApp Cloud API (Meta)

Come collegare il webhook dell'app Meta al CRM, così i messaggi in arrivo sui numeri WhatsApp Business API e gli stati dei messaggi inviati (consegnato, letto, errore) arrivano in tempo reale.

Endpoint

Verifica dell'URL: Meta lo chiama una volta, quando salvi la configurazione.

Notifiche: Meta lo chiama a ogni messaggio in arrivo e a ogni cambio di stato di un messaggio inviato.

Prerequisiti

• Un'app su Meta for Developers di tipo Business, con il prodotto WhatsApp aggiunto.
• Un account WhatsApp Business (WABA) con almeno un numero registrato sulla Cloud API.
• Il verify token del CRM: è il parametro waWhVerifyToken della configurazione del CRM (config/services.yaml). Lo fornisce il team AD HOC e non va pubblicato.

Configurazione

1. Registra il numero nel CRM. In WhatsApp → Dispositivi crea (o apri) il dispositivo di tipologia API e compila Phone Number ID, WABA ID e Access Token. Il Phone Number ID (non il numero di telefono) è la chiave con cui il CRM riconosce a quale dispositivo, e quindi a quale azienda, appartiene ogni notifica. Si trova in Meta for Developers → WhatsApp → API Setup, oppure in WhatsApp Manager → Numeri di telefono. Con il collegamento guidato («Collega WhatsApp API») questi dati vengono compilati da soli.
2. Apri la configurazione del webhook. In Meta for Developers apri l'app, poi WhatsApp → Configuration (Configurazione), sezione Webhook, e premi Modifica.
3. Inserisci URL e token.

   Callback URL	https://crm.adhocweb.it/wa/wh/message/receive
   Verify token	il valore di waWhVerifyToken

   Premi Verifica e salva. Meta chiama l'URL in GET con hub.mode=subscribe, hub.verify_token e hub.challenge: se il token coincide il CRM risponde con il challenge e Meta salva la configurazione. Se il token è sbagliato la risposta è 403 e Meta mostra un errore.
4. Sottoscrivi il campo messages. Nella stessa pagina, in Webhook fields, premi Subscribe accanto a messages. È l'unico campo che serve: comprende sia i messaggi in arrivo sia gli stati dei messaggi inviati. Gli altri campi non vengono letti dal CRM.
5. Iscrivi l'app al WABA. Meta invia le notifiche di un account WhatsApp Business solo alle app iscritte a quell'account. Il collegamento guidato lo fa da solo; se il numero è stato aggiunto a mano, iscrivi l'app con una chiamata alla Graph API usando l'access token del WABA:

   curl -X POST "https://graph.facebook.com/v25.0/WABA_ID/subscribed_apps" \
     -H "Authorization: Bearer ACCESS_TOKEN"
   # risposta attesa: {"success": true}
   
   # per controllare le app iscritte:
   curl "https://graph.facebook.com/v25.0/WABA_ID/subscribed_apps" \
     -H "Authorization: Bearer ACCESS_TOKEN"

6. Prova. Scrivi un messaggio WhatsApp al numero collegato: deve comparire nelle chat del CRM entro pochi secondi. Dalla pagina Configuration puoi anche usare Test accanto al campo messages: il messaggio di prova di Meta ha un Phone Number ID fittizio, quindi il CRM lo registra nel log ma non lo associa a nessuna azienda.

Cosa fa il CRM con le notifiche

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "39073300000", "phone_number_id": "PHONE_NUMBER_ID" },
        "contacts": [{ "profile": { "name": "Mario Rossi" }, "wa_id": "393331234567" }],
        "messages": [{ "from": "393331234567", "id": "wamid.HBgM...", "timestamp": "1760950000", "type": "text", "text": { "body": "Ciao!" } }]
      }
    }]
  }]
}

WhatsApp Flows (facoltativo)

I moduli WhatsApp (Flows) con dati dinamici usano un endpoint diverso, che si imposta sul singolo Flow in WhatsApp Manager e non nel webhook dell'app:

• Meta cifra ogni richiesta: sul server del CRM servono la chiave privata RSA (WA_FLOWS_PRIVATE_KEY ed eventuale WA_FLOWS_PASSPHRASE in .env.local), e la chiave pubblica corrispondente va caricata su Meta per il numero.
• Con WA_FLOWS_APP_SECRET (app secret dell'app Meta) il CRM verifica anche la firma X-Hub-Signature-256 di ogni richiesta.
• Senza chiave privata configurata l'endpoint risponde 500; se la decifratura fallisce risponde 421 e Meta rilegge la chiave pubblica e ritenta.

Risoluzione dei problemi