WhatsApp Commerce Suite: installatie- en configuratiehandleiding

Overzicht

DataFirefly WhatsApp Commerce Suite maakt van WhatsApp een volwaardig verkoopkanaal voor WooCommerce, via de officiële Meta Cloud API. De plugin bevat 4 modules die u los van elkaar kunt inschakelen: synchronisatie van de Meta Commerce-catalogus, bestellen via een gesprek, herinneringen bij een verlaten winkelwagen en een ondertekende betaallink.

Installatie

1. Download dfwhatsappcommerce-1.0.0.zip vanuit uw DataFirefly-klantaccount.
2. Ga in wp-admin naar Plugins → Nieuwe plugin → Plugin uploaden, selecteer de ZIP en klik op Nu installeren.
3. Activeer de plugin. Er verschijnt een nieuw menu WhatsApp in de beheerzijbalk.

Bij activering maakt de plugin 5 SQL-tabellen aan met het voorvoegsel dfwc_ (gesprekken, berichten, verlaten winkelwagens, cataloguslogboek, logboeken) en plant ze 3 cron-gebeurtenissen in: verwerking van de winkelwagens elke 15 minuten, dagelijkse opruiming van de logs, en synchronisatie van de catalogus in blokken, elk uur.

Vereisten aan Meta-zijde

Verzamel vóór het instellen van de plugin deze 5 waarden in Meta Business Suite:

• Phone Number ID: WhatsApp → API-configuratie → uw nummer
• WhatsApp Business Account ID: zichtbaar in de instellingen van het WhatsApp Business-account
• Catalog ID: Commerce Manager → uw catalogus → Instellingen
• Permanent Access Token: maak een systeemgebruiker aan via Business Settings → Users → System Users, ken die de rechten whatsapp_business_messaging, whatsapp_business_management en catalog_management toe, en genereer daarna een token zonder vervaldatum
• App Secret: Meta for Developers → uw applicatie → Instellingen → Algemeen

De plugin instellen

1. Ga naar WhatsApp → Instellingen.
2. Plak in het onderdeel Meta Cloud API-gegevens de 5 waarden die u hierboven hebt opgehaald. Het veld Webhook Verify Token wordt automatisch vooraf gegenereerd; wijzig het alleen als dat nodig is.
3. Vul het getoonde WhatsApp-nummer in, in E.164-formaat zonder plusteken (bijvoorbeeld 31612345678). Dat nummer wordt gebruikt voor de zwevende knop en de oproepen tot actie.
4. Schakel de gewenste modules in bij het onderdeel Modules. U kunt met alleen de catalogussynchronisatie beginnen en de rest geleidelijk inschakelen.
5. Sla op.

De Meta-webhook instellen

Via de webhook stuurt Meta de binnenkomende berichten en de afleverstatussen naar uw site.

1. Open WhatsApp → Dashboard in wp-admin: de Callback URL en het Verify Token staan daar, met kopieerknoppen.
2. Open in Meta for Developers uw applicatie → WhatsApp → Configuratie → Webhook.
3. Plak de Callback URL en het Verify Token en klik op Verifiëren en opslaan.
4. Abonneer u in de lijst met velden op messages.

De Callback URL heeft de vorm https://uw-site.com/wp-json/dfwc/v1/webhook. Elk binnenkomend verzoek wordt gevalideerd met een HMAC SHA-256-handtekening op basis van uw App Secret: niet of verkeerd ondertekende verzoeken worden geweigerd.

De verbinding testen

Via WhatsApp → Dashboard:

• API-verbinding testen: controleert uw gegevens door uw Phone Number ID op te vragen en toont het geverifieerde nummer.
• Testbericht versturen: vul een nummer in E.164-formaat zonder plusteken in en verstuur een tekstbericht als test.

Module 1: catalogussynchronisatie

Er zijn drie modi beschikbaar in de instellingen:

• Realtime: elke aanmaak, wijziging, voorraadmutatie of verwijdering van een product wordt meteen in de Meta-catalogus doorgevoerd.
• In blokken: de wijzigingen worden verzameld en elk uur in blokken van 50 doorgestuurd.
• Handmatig: er wordt niets automatisch verstuurd; u gebruikt de knop om opnieuw te synchroniseren.

Koppelingsregels:

• Elk product krijgt een retailer_id van de vorm wc_{ID}.
• Variabele producten gaan niet als geheel mee: elke variatie wordt afzonderlijk doorgestuurd, met eigen prijs, voorraad en afbeelding.
• Producten zonder afbeelding worden overgeslagen (eis van Meta).
• Met het filter dfwc_catalog_product_eligible sluit u producten via code uit, en met dfwc_catalog_product_data past u de verstuurde gegevens aan.

De pagina WhatsApp → Catalogus toont de tellers voor geslaagd en mislukt, het logboek van de 50 laatste gebeurtenissen, en de knop Hersynchronisatie starten, die alle in aanmerking komende producten in blokken van 100 opnieuw doorstuurt.

Module 2: bestellen via een gesprek

De gespreksmodule beantwoordt binnenkomende berichten automatisch volgens een toestandsmachine: idle → browsing → selecting_qty → reviewing → awaiting_payment, plus een toestand human_handoff.

Herkende sleutelwoorden (Frans en Engels binnen hetzelfde gesprek):

• menu of catalogue: toont de interactieve productlijst (tot 30 items, gekoppeld aan de Meta-catalogus)
• panier of cart: toont de inhoud van de winkelwagen met de knoppen Betalen, Verder winkelen en Legen
• commander, payer of checkout: maakt de betaallink aan
• humain, conseiller of aide: draagt over aan een medewerker (er gaat een e-mail naar het ingestelde adres)
• reset of annuler: zet het gesprek terug op nul

Elke andere tekst start een vrije zoekopdracht in uw producten. De winkelwagen van de klant blijft in het gesprek bewaard en wordt aan zijn WooCommerce-account gekoppeld als zijn nummer overeenkomt met een bestaand billing_phone.

Het welkomstbericht en het terugvalbericht zijn aan te passen in de instellingen. De pagina WhatsApp → Gesprekken toont alle gesprekken en laat u elk gesprek bekijken in een weergave in de stijl van WhatsApp Web.

Module 3: herinnering bij een verlaten winkelwagen

Zo werkt het:

1. De plugin legt de winkelwagen van de bezoekers vast (WooCommerce-sessie plus een reservecookie van 7 dagen) en maakt het telefoonveld verplicht bij het afrekenen.
2. Na de wachttijd voor het verlaten (standaard 60 minuten) vertrekt de eerste herinnering. Herinnering 2 en 3 volgen volgens hun eigen wachttijden (standaard 24 en 72 uur, in de instellingen uitgedrukt in minuten).
3. Elke herinnering gebruikt een HSM-template van Meta dat u per stap instelt. Mislukt het template, dan wordt een eenvoudig tekstbericht als terugval geprobeerd.
4. De derde herinnering kan een bestaande WooCommerce-kortingscode meesturen, die via de herstellink automatisch bij het afrekenen wordt toegepast.
5. Zodra de klant zijn bestelling afrondt, wordt de winkelwagen als hersteld gemarkeerd en stoppen de herinneringen.

De HSM-templates aanmaken

Maak in Meta Business Suite → WhatsApp Manager → Berichtsjablonen 3 templates aan (bijvoorbeeld dfwc_abandoned_cart_1, _2 en _3) met:

• een tekst met twee variabelen: {{1}} voor de voornaam van de klant en {{2}} voor het bedrag van de winkelwagen;
• een actieknop van het type URL met een variabele {{1}} aan het einde van de URL, die verwijst naar https://uw-site.com/wp-json/dfwc/v1/recover/{{1}}.

Maak elk template aan in de talen van uw klanten: de plugin herkent de locale en verstuurt de juiste versie. Zodra Meta de templates heeft goedgekeurd, vult u hun namen in bij de instellingen van de plugin.

De pagina WhatsApp → Verlaten winkelwagens toont het totaal, de winkelwagens waarvoor herinneringen lopen, de herstelde winkelwagens en het herstelpercentage.

Module 4: betaling en meldingen

De betaallink die in het gesprek wordt aangemaakt, is een met HMAC ondertekend token (SHA-256, WordPress-salt plus het geheim van de plugin) dat de winkelwagen, de vervaltijd en de gespreksidentificatie bevat. Wanneer de klant erop klikt:

1. wordt het token gevalideerd en gedecodeerd;
2. wordt de WooCommerce-winkelwagen aan de serverzijde opnieuw opgebouwd;
3. wordt het telefoonnummer van de klant vooraf ingevuld bij het afrekenen;
4. wordt de URL via een omleiding opgeschoond.

De geldigheidsduur van de link is instelbaar (Instellingen → Betaling). Bij een verlopen link verschijnt een foutmelding met de uitnodiging om via WhatsApp een nieuwe aan te vragen.

Automatische meldingen (elk afzonderlijk in te schakelen):

• Bestelling bevestigd: verstuurd bij de overgang naar Processing, met nummer en totaal.
• Bestelling verzonden: verstuurd bij de overgang naar Completed, met het trackingnummer dat wordt herkend uit Shipment Tracking, AfterShip of de meta _tracking_number, plus een knop om de zending te volgen.
• Betaling mislukt: verstuurd bij de overgang naar Failed, met een knop om de betaling opnieuw te proberen.

Zwevende knop en oproepen tot actie

• Zwevende knop: in te schakelen in de instellingen, met een positie naar keuze in een van de 4 hoeken, een aanpasbaar label en de mogelijkheid om hem te verbergen. Het template templates/frontend/whatsapp-button.php kunt u overschrijven door het te kopiëren naar uw-thema/dfwhatsappcommerce/whatsapp-button.php.
• Knop op de productpagina: “Bestellen via WhatsApp” onder de knop om aan de winkelwagen toe te voegen, met een vooraf ingevuld bericht met de naam en de link van het product.
• Knop in de winkelwagen: “Afronden via WhatsApp”, met het totaal van de winkelwagen.
• Knop bij het afrekenen: een discrete hulplink.
• Shortcode: [dfwc_whatsapp_button text="..." message="..."] om hem handmatig waar dan ook te plaatsen.

Kliks op al deze elementen worden in de dataLayer gezet (voorvoegsel dfwc_) voor GA4 en Google Tag Manager.

Logboeken en probleemoplossing

De pagina WhatsApp → Logboeken toont alle gebeurtenissen, met filters op niveau (debug tot critical) en op kanaal (api, webhook, catalog, conversation, cart, payment). Het logniveau en de bewaartermijn zijn instelbaar. De logs zijn ook zichtbaar via WooCommerce → Status → Logs, onder de bronnen dfwhatsappcommerce-*.

Veelvoorkomende problemen:

• De webhook wordt niet geverifieerd: controleer of uw site op HTTPS draait met een geldig certificaat, of de permalinks niet op “Eenvoudig” staan, en of het Verify Token bij Meta identiek is aan dat in de instellingen.
• Binnenkomende berichten komen niet aan: controleer of het veld messages wel is aangevinkt in de webhookconfiguratie bij Meta, en of het App Secret klopt (bij een ongeldige handtekening worden verzoeken stilzwijgend geweigerd, zichtbaar in het logboekkanaal webhook).
• De catalogussynchronisatie mislukt: controleer of het systeemtoken het recht catalog_management heeft en of het Catalog ID hoort bij de catalogus die aan uw WhatsApp Business-account is gekoppeld.
• De herinneringen vertrekken niet: controleer of de WordPress-cron werkt (met WP Crontrol ziet u dfwc_process_abandoned_carts) en of de HSM-templates door Meta zijn goedgekeurd.

Verwijderen

De plugin deactiveren behoudt alle gegevens. Definitief verwijderen via de pluginpagina start uninstall.php: de 5 tabellen worden verwijderd en de opties en cron-gebeurtenissen gewist. De WooCommerce-bestellingen die via WhatsApp zijn aangemaakt, worden nooit geraakt.