WhatsApp Commerce Suite — Guida di installazione e configurazione

Panoramica

DataFirefly WhatsApp Commerce Suite trasforma WhatsApp in un canale di vendita completo per WooCommerce, tramite la Cloud API ufficiale di Meta. Il plugin include 4 moduli attivabili in modo indipendente: sincronizzazione del catalogo Meta Commerce, presa ordini conversazionale, recupero carrello abbandonato e link di pagamento firmato.

Installazione

1. Scarica dfwhatsappcommerce-1.0.0.zip dal tuo account cliente DataFirefly.
2. In wp-admin, vai su Plugin → Aggiungi nuovo → Carica plugin, seleziona lo ZIP e fai clic su Installa ora.
3. Attiva il plugin. Un nuovo menu WhatsApp appare nella barra laterale dell’amministrazione.

All’attivazione, il plugin crea 5 tabelle SQL con prefisso dfwc_ (conversazioni, messaggi, carrelli abbandonati, log catalogo, log) e pianifica 3 eventi cron: elaborazione dei carrelli ogni 15 minuti, pulizia giornaliera dei log, e sincronizzazione catalogo in batch ogni ora.

Prerequisiti lato Meta

Prima di configurare il plugin, raccogli questi 5 valori da Meta Business Suite:

• Phone Number ID — WhatsApp → Configurazione API → il tuo numero
• WhatsApp Business Account ID — visibile nelle impostazioni del tuo account WhatsApp Business
• Catalog ID — Commerce Manager → il tuo catalogo → Impostazioni
• Access Token permanente — crea un utente di sistema in Business Settings → Users → System Users, assegnagli i permessi whatsapp_business_messaging, whatsapp_business_management e catalog_management, poi genera un token senza scadenza
• App Secret — Meta for Developers → la tua app → Impostazioni → Di base

Configurazione del plugin

1. Vai su WhatsApp → Impostazioni.
2. Nella sezione Credenziali Meta Cloud API, incolla i 5 valori raccolti sopra. Il campo Webhook Verify Token è pregenerato automaticamente — modificalo solo se necessario.
3. Inserisci il Numero WhatsApp mostrato in formato E.164 senza il segno + (esempio: 393331234567). Questo numero alimenta il pulsante fluttuante e i CTA.
4. Attiva i moduli desiderati nella sezione Moduli. Puoi iniziare solo con la sincronizzazione del catalogo e attivare il resto progressivamente.
5. Salva.

Configurazione del webhook Meta

Il webhook consente a Meta di consegnare i messaggi in arrivo e gli stati di consegna al tuo sito.

1. Apri WhatsApp → Pannello in wp-admin: la Callback URL e il Verify Token sono mostrati lì con pulsanti Copia.
2. In Meta for Developers, apri la tua app → WhatsApp → Configurazione → Webhook.
3. Incolla la Callback URL e il Verify Token, poi fai clic su Verifica e salva.
4. Nell’elenco dei campi, iscriviti a messages.

La Callback URL ha la forma https://tuo-sito.it/wp-json/dfwc/v1/webhook. Ogni richiesta in arrivo è validata con firma HMAC SHA-256 contro il tuo App Secret: le richieste non firmate o mal firmate vengono rifiutate.

Test della connessione

Da WhatsApp → Pannello:

• Testa la connessione API — verifica le tue credenziali interrogando il tuo Phone Number ID e mostra il numero verificato.
• Invia un messaggio di prova — inserisci un numero in formato E.164 senza + e invia un messaggio di testo di prova.

Modulo 1 — Sincronizzazione del catalogo

Tre modalità disponibili nelle Impostazioni:

• Tempo reale — ogni creazione, modifica, cambio di stock o eliminazione di prodotto viene immediatamente riflessa nel catalogo Meta.
• In batch — le modifiche si accumulano e vengono inviate ogni ora in batch da 50.
• Manuale — nulla viene inviato automaticamente; usi il pulsante di risincronizzazione.

Regole di mapping:

• Ogni prodotto riceve un retailer_id nella forma wc_{ID}.
• I prodotti variabili non vengono inviati come tali: ogni variazione viene inviata individualmente con il proprio prezzo, stock e immagine.
• I prodotti senza immagine vengono saltati (requisito Meta).
• Il filtro dfwc_catalog_product_eligible permette di escludere prodotti via codice, e dfwc_catalog_product_data di modificare i dati inviati.

La pagina WhatsApp → Catalogo mostra i contatori di successo ed errore, il log degli ultimi 50 eventi, e il pulsante Avvia risincronizzazione che reinvia tutti i prodotti idonei in batch da 100.

Modulo 2 — Ordine conversazionale

Il modulo conversazione risponde automaticamente ai messaggi in arrivo secondo una macchina a stati: idle → browsing → selecting_qty → reviewing → awaiting_payment, più uno stato human_handoff.

Parole chiave riconosciute (francese e inglese nella stessa conversazione):

• menu o catalogue — mostra la lista interattiva dei prodotti (fino a 30 elementi, collegati al catalogo Meta)
• cart o panier — mostra il contenuto del carrello con i pulsanti Paga / Continua / Svuota
• checkout, pay o payer — genera il link di pagamento
• human, humain o aide — trasferisce a un consulente (e-mail inviata all’indirizzo configurato)
• reset o annuler — reimposta la conversazione

Qualsiasi altro testo attiva una ricerca libera nei tuoi prodotti. Il carrello del cliente viene conservato nella conversazione e collegato al suo account WooCommerce se il suo numero corrisponde a un billing_phone esistente.

I messaggi di benvenuto e di fallback sono personalizzabili nelle Impostazioni. La pagina WhatsApp → Conversazioni elenca tutte le conversazioni e permette di consultare ogni thread in una vista stile WhatsApp Web.

Modulo 3 — Recupero carrello abbandonato

Funzionamento:

1. Il plugin cattura il carrello dei visitatori (sessione WooCommerce + cookie di riserva di 7 giorni) e rende obbligatorio il campo telefono al checkout.
2. Dopo la soglia di abbandono (60 minuti di default), parte il primo sollecito. I solleciti 2 e 3 seguono i propri ritardi (24h e 72h di default, espressi in minuti nelle Impostazioni).
3. Ogni sollecito usa un template HSM Meta configurato per fase. Se il template fallisce, viene tentato un messaggio di testo semplice come riserva.
4. Il terzo sollecito può allegare un codice sconto WooCommerce esistente, applicato automaticamente al checkout tramite il link di recupero.
5. Quando il cliente completa l’ordine, il carrello viene marcato come recuperato e i solleciti si fermano.

Creazione dei template HSM

In Meta Business Suite → WhatsApp Manager → Modelli di messaggio, crea 3 template (ad esempio dfwc_abandoned_cart_1, _2, _3) con:

• Un corpo con due variabili: {{1}} = nome del cliente, {{2}} = importo del carrello
• Un pulsante di azione di tipo URL con una variabile {{1}} alla fine dell’URL, che punta a https://tuo-sito.it/wp-json/dfwc/v1/recover/{{1}}

Crea ogni template nelle lingue dei tuoi clienti: il plugin rileva la locale e invia la versione giusta. Una volta approvati da Meta, inserisci i loro nomi nelle Impostazioni del plugin.

La pagina WhatsApp → Carrelli abbandonati mostra il totale, i carrelli in sollecito, quelli recuperati e il tasso di recupero.

Modulo 4 — Pagamento e notifiche

Il link di pagamento generato nella conversazione è un token firmato HMAC (SHA-256, salt di WordPress + segreto del plugin) contenente il carrello, la scadenza e l’identificativo della conversazione. Quando il cliente fa clic:

1. Il token viene validato e decodificato.
2. Il carrello WooCommerce viene ricostruito lato server.
3. Il telefono del cliente viene precompilato al checkout.
4. L’URL viene pulito con un redirect.

La validità del link è configurabile (Impostazioni → Pagamento). Un link scaduto mostra un messaggio di errore che invita a richiederne uno nuovo via WhatsApp.

Notifiche automatiche (attivabili individualmente):

• Ordine confermato — inviata al passaggio a Processing, con numero e totale.
• Ordine spedito — inviata al passaggio a Completed, con il numero di tracciamento rilevato da Shipment Tracking, AfterShip o dalla meta _tracking_number, e un pulsante CTA di tracciamento.
• Pagamento fallito — inviata al passaggio a Failed, con un pulsante per riprovare il pagamento.

Pulsante fluttuante e CTA

• Pulsante fluttuante — attivabile nelle Impostazioni, posizione in uno dei 4 angoli, etichetta personalizzabile, nascondibile. Il template templates/frontend/whatsapp-button.php può essere sovrascritto copiandolo in tuo-tema/dfwhatsappcommerce/whatsapp-button.php.
• CTA pagina prodotto — pulsante «Ordina via WhatsApp» sotto il pulsante aggiungi al carrello, con messaggio precompilato con nome e link del prodotto.
• CTA carrello — pulsante «Completa via WhatsApp» con il totale del carrello.
• CTA checkout — link di aiuto discreto.
• Shortcode — [dfwc_whatsapp_button text="..." message="..."] per il posizionamento manuale ovunque.

I clic su tutti questi elementi vengono inviati al dataLayer (prefisso dfwc_) per GA4 / Google Tag Manager.

Log e risoluzione dei problemi

La pagina WhatsApp → Log mostra tutti gli eventi con filtri per livello (debug → critical) e per canale (api, webhook, catalog, conversation, cart, payment). Il livello di log e la conservazione sono configurabili. I log sono visibili anche in WooCommerce → Stato → Log sotto le fonti dfwhatsappcommerce-*.

Problemi comuni:

• Il webhook non si verifica — verifica che il tuo sito sia in HTTPS con certificato valido, che i permalink non siano in modalità «Semplice», e che il Verify Token incollato su Meta sia identico a quello delle Impostazioni.
• I messaggi in arrivo non arrivano — verifica che il campo messages sia sottoscritto nella configurazione del webhook Meta, e che l’App Secret sia corretto (una firma non valida rifiuta silenziosamente le richieste — visibile nei Log, canale webhook).
• La sincronizzazione del catalogo fallisce — verifica che il token di sistema abbia il permesso catalog_management e che il Catalog ID corrisponda al catalogo collegato al tuo account WhatsApp Business.
• I solleciti non partono — verifica che il cron di WordPress funzioni (WP Crontrol permette di visualizzare dfwc_process_abandoned_carts), e che i template HSM siano approvati da Meta.

Disinstallazione

La disattivazione del plugin conserva tutti i dati. L’eliminazione definitiva dalla pagina Plugin esegue uninstall.php: le 5 tabelle vengono eliminate, le opzioni e gli eventi cron rimossi. Gli ordini WooCommerce creati via WhatsApp non vengono mai toccati.