AI-klantenservice-agent: volledige documentatie

Volledige handleiding voor installatie, configuratie en gebruik van de plugin DataFirefly AI Customer Service Agent, een AI-klantenservice-agent voor WooCommerce die de context begrijpt, alleen-lezen tools op uw winkel aanroept en complexe gevallen doordacht doorschuift naar Slack en e-mail.

1. Vereisten

• WordPress 6.4 of hoger
• WooCommerce 8.0 of hoger
• PHP 8.1, 8.2 of 8.3
• Een API-sleutel van Anthropic (Claude) of OpenAI (aanbevolen: Claude Sonnet 4.5)
• Optioneel: een Slack-webhook voor escalatie in realtime
• Optioneel: Polylang Pro of WPML als uw winkel meertalig is

2. Installatie

De ZIP installeren

1. Download vanuit uw DataFirefly-account het bestand df-ai-customer-service.zip.
2. Ga in WordPress naar Plugins → Nieuwe plugin → Plugin uploaden.
3. Selecteer de ZIP en klik op Installeren.
4. Klik na de installatie op Activeren.

Wat gebeurt er bij de activering?

De plugin maakt automatisch 5 tabellen aan in de database met het voorvoegsel wp_dfaics_: conversations, messages, escalations, faq en analytics. Ze verklaart ook haar compatibiliteit met HPOS en met de Gutenberg-blokken voor winkelwagen en afrekenen, en plant daarna een dagelijkse crontaak in om verlopen gesprekken op te ruimen.

3. De AI-provider instellen

De plugin ondersteunt twee AI-providers. U kiest zelf welke, via AI Support → Instellingen → AI. U levert uw eigen API-sleutel aan; DataFirefly onderschept niets en houdt geen commissie in op uw verbruik.

Optie A: Claude (aanbevolen)

1. Maak een account aan op console.anthropic.com.
2. Genereer een API-sleutel bij Settings → API Keys.
3. Kopieer de sleutel (die begint met sk-ant-...).
4. Ga in WordPress naar AI Support → Instellingen → AI.
5. Selecteer de provider Anthropic (Claude).
6. Plak uw sleutel in het veld Anthropic API-sleutel.
7. Standaardmodel: claude-sonnet-4-5 (uitstekende verhouding tussen kwaliteit en kosten).
8. Klik op Sleutel testen om te valideren.
9. Sla op.

Optie B: OpenAI

1. Maak een account aan op platform.openai.com.
2. Genereer een API-sleutel bij API Keys.
3. Kopieer de sleutel (die begint met sk-...).
4. Selecteer in WordPress de provider OpenAI.
5. Standaardmodel: gpt-4o-mini (het voordeligste met betrouwbare tool calling).

Indicatieve kosten

Een typisch gesprek van 5 tot 10 beurten met tool calling kost:

• ongeveer 0,01 tot 0,05 USD met Claude Sonnet 4.5;
• ongeveer 0,005 tot 0,02 USD met GPT-4o mini.

Het dashboard toont het totale aantal verbruikte input- en outputtokens over de periode.

4. De widget instellen

De chatwidget verschijnt standaard rechtsonder op alle pagina’s van de website. U past hem aan via AI Support → Instellingen → Widget.

Weergaveopties

• Hoofdkleur: de kleur van de zwevende knop en de kop (standaard #0073aa)
• Tekstkleur: de kleur van de tekst in de kop (standaard wit)
• Positie: rechtsonder of linksonder
• Titel van de widget: bijvoorbeeld “Hulp nodig?”
• Welkomstbericht: het eerste bericht dat bij het openen verschijnt
• Placeholder: de tekst in het invoerveld
• DataFirefly-badge tonen: een kleine vermelding onder aan de widget

Voorwaardelijke weergave

Op het tabblad Widget kunt u de weergave beperken:

• Alle pagina’s: het standaardgedrag
• Alleen productpagina’s: voor gerichte hulp op de productpagina’s
• Behalve winkelwagen en afrekenen: om afleiding tijdens de aankoop te vermijden
• Verbergen bij deze inhouds-ID’s: een lijst met uit te sluiten ID’s

Shortcode

U kunt de chat ook in een pagina of bericht plaatsen met de shortcode:

[dfaics_chat]

Dat toont de widget in ingebedde modus (niet zwevend), handig voor een aparte contactpagina.

5. De 6 tools van de agent

De agent beschikt over 6 tools, die hij naargelang de vraag wel of niet aanroept. Ze zijn allemaal strikt alleen-lezen. U schakelt ze afzonderlijk in of uit via Instellingen → Gedrag.

lookup_order

Haalt de status van een WooCommerce-bestelling op. Vereist verplicht een e-mailcontrole vóór het vrijgeven van gegevens: de agent vraagt het e-mailadres aan de klant en vergelijkt dat met het adres op de bestelling. Geeft nummer, status, bedrag, datum, verzendmethode en het trackingnummer terug indien beschikbaar.

search_products

Zoekt in de catalogus op naam, categorie, tag, beschikbaarheid en prijsklasse. Geeft standaard tot 5 resultaten terug met titel, SKU, prijs, URL en voorraad. Handig om te antwoorden op “hebben jullie dit in het blauw?” of “wat kost X?”.

get_shipping_info

Geeft de verzendzones en -methoden terug die in WooCommerce zijn ingesteld, met kosten en levertijden. Zo kan de agent precies antwoorden op “leveren jullie in België?” of “wat kost express?”.

get_returns_policy

Geeft de inhoud van uw retourbeleid terug (dat u in de instellingen vastlegt). De agent kan zo de termijn, de procedure en de voorwaarden uitleggen.

search_faq

Zoekt in uw eigen FAQ’s (beheerd via AI Support → FAQ). De resultaten zijn afgebakend per taal van het gesprek. Elk gevonden item verhoogt een gebruiksteller, waarmee u de meest voorkomende vragen kunt herkennen.

escalate_to_human

De agent roept deze tool aan wanneer hij vaststelt dat een geval een mens vereist (frustratie bij de klant, complexe situatie, meerdere mislukte tools). Dat start de ingestelde meldingen via Slack en/of e-mail. Zie het onderdeel Escalatie verderop.

6. De FAQ beheren

Maak eigen FAQ-items aan waarin de agent tijdens een gesprek kan zoeken. Elk item is per taal afgebakend.

Een item aanmaken

1. Ga naar AI Support → FAQ.
2. Klik op Item toevoegen.
3. Kies de taal.
4. Schrijf de vraag en het antwoord in natuurlijke taal.
5. Voeg sleutelwoorden toe, gescheiden door komma’s (optioneel, verbetert het zoeken).
6. Kies een categorie (bijvoorbeeld levering, maten, garantie).
7. Sla op.

Goede gewoonten voor de FAQ

• Formuleer de vragen zoals een klant ze zou stellen, niet zoals een SEO-redacteur.
• Houd de antwoorden kort en bruikbaar (2 tot 4 zinnen volstaan, de agent herformuleert).
• Maak een item aan per belangrijke taal van uw klantenbestand.
• Bekijk de gebruiksteller regelmatig om te zien welke vragen u kunt aanvullen.

7. Escalatie naar een mens

De escalatie stelt u in via Instellingen → Escalatie. Er worden twee kanalen naast elkaar ondersteund: Slack en e-mail.

Slack instellen

1. Maak in Slack een nieuwe app aan op api.slack.com/apps.
2. Schakel Incoming Webhooks in.
3. Maak een webhook naar het gewenste kanaal (bijvoorbeeld #support-escalations).
4. Kopieer de URL van de webhook.
5. Plak die in WordPress in het veld Slack-webhook.
6. Klik op Webhook testen om een testbericht te versturen.

Bij elke escalatie gaat er naar Slack een bericht in rijke blokken met: een fragment van de 3 laatste berichten, de reden van de escalatie, de klantgegevens (geverifieerd e-mailadres, taal, pagina van herkomst) en een knop Openen in het beheer die rechtstreeks naar het detail van het gesprek verwijst.

E-mail instellen

Geef bij E-mailadres voor escalatie een of meer adressen op, gescheiden door komma’s. Bij elke escalatie gaat er een HTML-e-mail uit met het volledige gesprek, de klantgegevens en een link naar het beheer.

Wat een escalatie in gang zet

De agent escaleert in 3 situaties:

1. Gevoelige sleutelwoorden: een instelbare lijst (standaard: terugbetaling, advocaat, kapot, klacht, complaint, refund, lawyer, broken).
2. Sentimentdrempel: herkenning van frustratie of ontevredenheid (instelbaar van -1 tot 0).
3. Herhaald falen van tools: na 6 beurten zonder oplossing volgt een gedwongen escalatie.

8. Dashboard en analyses

Het dashboard AI Support → Dashboard toont 4 kernindicatoren:

• Volume: het totale aantal gesprekken over de laatste 7, 30 of 90 dagen
• Percentage zelf opgelost: het aandeel gesprekken dat zonder escalatie eindigt
• Gemiddelde tevredenheid: de sterrenbeoordeling die klanten na een escalatie geven
• Verbruikte tokens: input plus output samen, voor een raming van de AI-kosten

De pagina Gesprekken toont alle sessies met filters (taal, status, wel of niet geëscaleerd). Klik op een regel om het volledige gesprek te zien, met de tool calls in detail in JSON.

9. Meertaligheid

De plugin ondersteunt vijf talen ingebouwd: Frans, Engels, Spaans, Duits en Italiaans. De taal van het gesprek wordt automatisch bepaald, in deze volgorde:

1. de Polylang-taal van de pagina waarop de widget staat (als Polylang is geïnstalleerd);
2. de WPML-taal van de pagina (als WPML is geïnstalleerd);
3. de locale van de browser van de bezoeker;
4. de terugvaltaal uit de instellingen (standaard Engels).

De systeemprompt van de agent geeft het model uitdrukkelijk aan in welke taal het moet antwoorden. Zo krijgt een Franstalige bezoeker een antwoord in het Frans, ook als uw winkel overwegend Engelstalig is.

10. Beveiliging en privacy

Versleuteling van de API-sleutels

De sleutels van Anthropic en OpenAI en de Slack-webhook worden bij het opslaan versleuteld in AES-256-CBC, met een sleutel die is afgeleid van AUTH_KEY plus AUTH_SALT. Het invoerveld toont de waarde nooit opnieuw: laat u het veld leeg en slaat u op, dan blijft de oude waarde behouden.

E-mailcontrole bij bestellingen

De tool lookup_order vereist altijd een controle: de agent vraagt de klant om zijn e-mailadres en vergelijkt dat met het adres bij de bestelling. Zonder overeenkomst worden er geen gegevens vrijgegeven. Dat gedrag is niet uit te schakelen; het beschermt tegen het uitlezen van bestellingen via de agent.

Snelheidslimiet

Er geldt aan de serverzijde een antispamlimiet van 5 berichten per minuut per sessie. Het maximale aantal berichten per gesprek is standaard 25 (instelbaar). Daarboven stelt de agent een escalatie naar een mens voor.

Bewaartermijn en AVG

De gesprekken blijven standaard 30 dagen bewaard en worden daarna automatisch verwijderd door een dagelijkse crontaak. U kunt die termijn verkorten via Instellingen → Privacy. Het IP-adres en de user agent van de bezoeker kunnen al dan niet worden gelogd, naargelang uw beleid.

De plugin biedt ook een optie Persoonsgegevens in de logs anonimiseren, die e-mailadressen en telefoonnummers in de technische logs maskeert (de WooCommerce-logger).

11. Compatibiliteit met HPOS en de afrekenblokken

De plugin verklaart officieel haar compatibiliteit met:

• HPOS (High-Performance Order Storage): alle bestelqueries verlopen via de officiële WooCommerce-CRUD’s (wc_get_order, wc_get_orders), en werken dus even goed op de oude tabellen als op de HPOS-tabellen;
• de Gutenberg-blokken voor winkelwagen en afrekenen: geen enkele storing met de nieuwe betaalblokken;
• WordPress Multisite: netwerkactivering wordt ondersteund, met opties per site.

12. Hooks en filters voor ontwikkelaars

De plugin biedt verschillende hooks om het gedrag aan te passen zonder de broncode te wijzigen.

Beschikbare filters

// De systeemprompt aanpassen vóór verzending naar het model
apply_filters('dfaics_system_prompt', $prompt, $context);

// Tools dynamisch toevoegen of verwijderen
apply_filters('dfaics_tools_available', $tools, $conversation);

// De drempel van het maximum aantal berichten vóór gedwongen escalatie wijzigen
apply_filters('dfaics_max_messages', 25, $conversation);

// De inhoud van de escalatiemail aanpassen
apply_filters('dfaics_escalation_email_body', $html, $conversation);

// De Slack-metagegevens uitbreiden
apply_filters('dfaics_slack_metadata', $metadata, $conversation);

Beschikbare acties

// Na het aanmaken van een gesprek
do_action('dfaics_conversation_created', $conversation_id, $session);

// Na het versturen van een bericht door de agent
do_action('dfaics_message_sent', $message_id, $conversation_id);

// Na een escalatie
do_action('dfaics_escalated', $conversation_id, $reason, $channel);

// Na de cron-opruiming van verlopen gesprekken
do_action('dfaics_cleanup_done', $deleted_count);

Een eigen tool toevoegen

Maak een klasse die ToolBase uitbreidt en registreer die via het filter dfaics_tools_available. De namespace is DataFireflyAiCustomerServiceAgentTools. Elke tool geeft zijn JSON-schema en beschrijving op en implementeert een methode execute() die een serialiseerbare associatieve array teruggeeft.

13. Probleemoplossing

De widget verschijnt niet

• Controleer of de widget is ingeschakeld bij Instellingen → Widget → Widget inschakelen.
• Controleer de regel voor voorwaardelijke weergave (toegestane pagina’s).
• Open de browserconsole (F12) en zoek naar JavaScript-fouten.
• Leeg de cache als u een cacheplugin gebruikt (WP Rocket, W3 Total Cache en andere).

De agent antwoordt niet

• Controleer of de API-sleutel geldig is via de knop Sleutel testen.
• Controleer uw tegoed of quotum bij het Anthropic- of OpenAI-account.
• Raadpleeg de WooCommerce-logs bij WooCommerce → Status → Logs, bron df-ai-customer-service.

De escalatie naar Slack komt niet aan

• Controleer de webhook via de knop Webhook testen.
• Genereer de webhook zo nodig opnieuw aan Slack-zijde.
• Controleer of het doelkanaal bestaat en of de bot er toegang toe heeft.

De plugin volledig resetten

Vink bij Instellingen → Privacy de optie Alle gegevens verwijderen bij het verwijderen van de plugin aan. Deactiveer en verwijder daarna de plugin: de 5 tabellen en de opties worden gewist.

14. Technische vraagbaak

Kan ik van AI-provider wisselen zonder de gesprekken kwijt te raken?

Ja, de overstap tussen Claude en OpenAI is meteen actief en raakt de historiek niet. Nieuwe gesprekken gebruiken de nieuwe provider.

Werkt de plugin in een headless opzet?

De REST API van de plugin (/wp-json/dfaics/v1/) is bruikbaar vanuit elke front-end (Next.js, Vue, mobiel). De ingebouwde widget is in vanilla JavaScript geschreven en kunt u vervangen door uw eigen implementatie, die dezelfde API aanroept.

Kan de plugin op Zendesk of Freshdesk worden aangesloten?

Niet ingebouwd in versie 1.0.0: de escalatie beperkt zich tot Slack en e-mail. U kunt wel de hook dfaics_escalated gebruiken om uw eigen integratie te starten.

Leert de agent van mijn gesprekken?

Nee. Er wordt geen enkele fine-tuning uitgevoerd. De agent gebruikt uitsluitend de systeemprompt, de tools en de context van het lopende gesprek. Uw gegevens worden niet gebruikt om de modellen van Anthropic of OpenAI te verbeteren (beide providers bieden een opt-out die op hun zakelijke API’s standaard actief is).

15. Support

Voor vragen of het melden van een bug schrijft u naar support at datafirefly.com, met vermelding van uw licentienummer. We antwoorden binnen 48 werkuren.