AI Personal Shopper documentatie

Installatie

Vereisten

Magento 2.4.x — getest op 2.4.9, compatibel met eerdere 2.4.*-versies. PHP 8.1–8.5. Compatibel met zowel het standaard Luma-thema als het Hyvä-thema (de chatwidget wordt weergegeven in een geïsoleerde Shadow DOM, dus identiek op beide, zonder templatewijzigingen). Vereist de gratis module codingrow/module-core, die automatisch wordt geïnstalleerd. Vereist een API-sleutel van minstens één AI-provider (OpenAI, Anthropic, Google of OpenRouter) — rechtstreeks door de provider aan jou gefactureerd.

Installatiestappen

1. Voeg de inloggegevens die je per e-mail ontvangt toe aan auth.json in de root van je Magento-project:

   { "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }

2. composer config repositories.codingrow composer https://repo.codingrow.com
3. composer require codingrow/module-ai-personal-shopper
4. bin/magento module:enable Codingrow_AiPersonalShopper
5. bin/magento setup:upgrade && bin/magento setup:di:compile
6. Plak je licentiesleutel bij Admin → Stores → Configuration → Codingrow → AI Personal Shopper → License → License Key, sla op, en voer dan bin/magento cache:flush uit.

Configuratie

Open Admin → Stores → Configuration → Codingrow → AI Personal Shopper. Vul de License Key in, zet Enable op Yes en loop dan de Capabilities na. Provider, model en API-sleutel staan hier niet: een AI voegt u toe op het tabblad AI Models (Codingrow → AI Personal Shopper → AI Models).

Verwijderen

Zet Enable op No en sla op om de widget meteen te verbergen. Om de module volledig te verwijderen: bin/magento module:disable Codingrow_AiPersonalShopper en dan composer remove codingrow/module-ai-personal-shopper.

AI-provider instellen

Een provider kiezen

De assistent werkt met elk van de vier providers — jij brengt je eigen API-sleutel mee, en het AI-gebruik wordt rechtstreeks door de gekozen provider aan jou gefactureerd. OpenAI (ChatGPT/GPT) biedt het breedste aanbod; Anthropic (Claude) past goed bij een assistent die zich strikt aan het script moet houden; Google (Gemini) heeft concurrerende prijzen en is snel; OpenRouter geeft je één sleutel voor tientallen modellen van verschillende providers, handig om kosten en kwaliteit te vergelijken.

Een OpenAI API-sleutel aanmaken

1. Log in op platform.openai.com.
2. Ga naar platform.openai.com/api-keys.
3. Klik op Create new secret key, geef een naam (bijv. "AI Personal Shopper") en kopieer hem meteen — hij wordt maar één keer getoond.
4. Voeg hem toe als nieuwe AI op het tabblad AI Models (Codingrow → AI Personal Shopper → AI Models) met Provider op OpenAI, en kies dan het model met Load models.

Een Anthropic API-sleutel aanmaken

1. Log in op console.anthropic.com.
2. Ga naar console.anthropic.com/settings/keys.
3. Klik op Create Key, geef een naam en kopieer de waarde.
4. Voeg hem toe als nieuwe AI op het tabblad AI Models (Codingrow → AI Personal Shopper → AI Models) met Provider op Anthropic, en kies dan het model met Load models.

Een Google API-sleutel aanmaken

1. Log in op aistudio.google.com met een Google-account.
2. Ga naar aistudio.google.com/app/apikey.
3. Klik op Create API key, kies of maak een Google Cloud-project en kopieer de sleutel.
4. Voeg hem toe als nieuwe AI op het tabblad AI Models (Codingrow → AI Personal Shopper → AI Models) met Provider op Google, en kies dan het model met Load models.

Een OpenRouter API-sleutel aanmaken

1. Log in op openrouter.ai.
2. Ga naar openrouter.ai/keys.
3. Klik op Create Key, geef een naam en kopieer de waarde.
4. Voeg hem toe als nieuwe AI op het tabblad AI Models (Codingrow → AI Personal Shopper → AI Models) met Provider op OpenRouter, en kies dan het model met Load models.

Load models

Zodra de API-sleutel is ingevuld, klik je onder het veld Model op Load models: de module raadpleegt met jouw sleutel het eigen model-lijst-endpoint van de provider en vult een keuzelijst met alle modellen die je sleutel daadwerkelijk kan gebruiken — kies uit de lijst in plaats van een id te typen. Een handmatig tekstveld blijft beschikbaar als terugval voor een model-id dat nog niet in de lijst staat. Vlak onder het veld staat altijd een link naar de juiste pagina om de sleutel van de op dat moment geselecteerde provider te krijgen.

Calculator voor budgetduur

AI-gebruik wordt door de provider per token gefactureerd, dus de natuurlijke vraag is hoe lang een bepaald budget meegaat. Het configuratiescherm beantwoordt dat direct: vlak onder de API-sleutels staat een kleine budgetcalculator. Voer je budget in, de modelprijs per miljoen input-/outputtokens (er zijn presets voor Gemini Flash, OpenAI gpt-4o-mini, Claude Haiku 4.5 en Claude Sonnet 4.5) en het verwachte aantal chats per dag. Hij toont direct de kosten per chat en hoeveel dagen het budget meegaat in een optimistisch scenario (korte chats) en een pessimistisch scenario (lange chats).

De aannames voor tokens per chat zijn gelijk over platforms — alleen de modelprijs verandert — dus de vergelijking is eerlijk. Een referentietabel laat ongeveer zien hoe ver een budget van €100 reikt op elk model bij ongeveer 10 chats per dag. Het is alleen een planningshulp; de werkelijke kosten worden altijd door de provider gefactureerd.

Kwaliteit versus kosten. De module geeft het model al alles wat het nodig heeft om te antwoorden en te helpen — catalogus, bestellingen, promoties, categorieën, synoniemen en tools. De kwaliteit van de antwoorden hangt vervolgens af van het gekozen model: als ze je niet bevallen, probeer dan simpelweg een ander model of een andere provider. De kosten volgen rechtstreeks uit die keuze — maar dit soort assistent heeft geen duur, "redenerend" of complex model nodig: een goedkoop, snel model (klasse "flash"/"mini") voldoet prima.

AI-afstemming en diagnostiek

Elke AI in de pool heeft zijn eigen instellingen, op zijn kaart op het tabblad AI Models — plus één limiet die in Configuration blijft:

• Max response tokens (op de AI-kaart) — begrenst de lengte van elk antwoord; lager houdt antwoorden kort en kosten laag.
• Temperature (op de AI-kaart) — van gericht en voorspelbaar tot meer gevarieerde formuleringen. Leeg gelaten wordt hij helemaal niet verzonden, en dat is wat de nieuwste modelfamilies vereisen.
• Max tool rounds (Stores → Configuration → … → Agent limits) — 1 tot 8, hoe vaak het model zijn gereedschappen (zoeken, orderstatus, …) mag aanroepen voordat het moet antwoorden; hoger geeft grondiger antwoorden in meer stappen, lager is sneller en goedkoper.
• Recent AI calls (diagnose) (tabblad AI Models) — de laatste 10 aanroepen met uitkomst, fout, bericht en antwoord: blijft een antwoord uit, dan ziet u meteen waarom. Met failover aan noemt hij de AI die echt geantwoord heeft, niet de primaire.

Belangrijke opmerking: de kwaliteit, consistentie en proactiviteit van de antwoorden hangen vooral af van het AI-model dat je kiest, niet alleen van de module. Een goedkoop, snel model (een "flash"-/"mini"-/Haiku-klasse) kost weinig maar is minder goed in het samenstellen van de volgorde van de kaarten, het terugbrengen van opties tot enkele, en het voorstellen van combinaties/cross-sell; een capabeler model (bijv. Claude Sonnet, een model uit de GPT-4-klasse) volgt deze logica veel betrouwbaarder. Als de antwoorden je niet bevallen, is het eerste wat je kunt proberen overschakelen naar een sterker model — de kosten veranderen dienovereenkomstig, gebruik de rekenmachine hierboven.

Gebruikershandleiding

Capabilities

Elke capability is een onafhankelijke schakelaar onder Capabilities. Een capability uitschakelen ontneemt de agent die mogelijkheid meteen — er wordt nooit meer aangenomen of afgeleid dan wat is ingeschakeld:

• Productzoeken — zoeken in natuurlijke taal in de live catalogus, teruggegeven als productkaarten (of categoriekaarten wanneer de vraag te vaag is voor één product).
• Bestelstatus — vraagt de echte bestelstatus op voor ingelogde klanten, of voor gasten die bestelnummer + e-mail bevestigen.
• Promoties — de agent kent actieve kortingen en kan ze noemen of erop filteren.
• Categorie-inhoud lezen — laat de agent de eigen PageBuilder-beschrijving van een categorie lezen (get_category_info), zodat koopgidsen, maattabellen en redactionele tekst die je al op categoriepagina's hebt geschreven het antwoord voeden in plaats van te worden genegeerd.
• Toevoegen aan winkelwagen — laat de klant een product rechtstreeks vanaf een kaart toevoegen, met een aantalkiezer, zonder de chat te verlaten.
• Spraakinvoer — klanten kunnen hun vraag inspreken in plaats van typen (Web Speech-microfoon).
• Zelflerende synoniemen — legt de koppeling vast tussen een mislukt zoekwoord en de catalogusterm die uiteindelijk overeenkwam.
• Tickets voor menselijke ondersteuning — laat de agent een ticket openen en overdragen aan een persoon wanneer een vraag écht een mens nodig heeft; schakel je dit uit, dan stelt de agent nooit voor om een ticket te openen.
• Afsluitende cross-sell-suggesties — wanneer de klant afrondt, kan de agent een of twee aanvullende producten toevoegen als laatste suggestie voordat hij afscheid neemt. Standaard uit; schakel het alleen in als je die afsluitende duw wilt.

De productbeleving

Alles wat de klant in de chat ziet — welke producten, in welke volgorde, en hoe de kaarten veranderen naarmate het gesprek vordert — wordt aangestuurd door de assistent, niet door een vaste resultatenlijst.

• Samengestelde, live kaarten — de assistent zoekt breed, kiest vervolgens welke producten te tonen en in welke volgorde, en stuurt naar 2–3 sterke opties in plaats van een muur aan resultaten te dumpen. De kaarten verversen in realtime bij elke beurt: naarmate de klant verfijnt ("die in mango", "iets goedkopers"), wordt het raster opnieuw opgebouwd om overeen te komen.
• Categoriekaarten — wanneer een vraag te vaag is voor één product ("een cadeau voor thuis, geen idee wat"), stelt de assistent categorieën voor om te verkennen in plaats van een doodlopend pad.
• Snelle antwoorden — klikbare optieknoppen onder een bericht, zodat de klant met een tik verder kan in plaats van te typen.
• Toevoegen aan winkelwagen — een aantalkiezer direct op de kaart bevestigt vóór het toevoegen; bij configureerbare producten opent de kaart zodat de klant eerst de opties kiest.
• Rijke kaarten — productkaarten tonen naam, afbeelding, prijs en eventuele korting, plus een "Tell me more"; bestelkaarten tonen de tracking (vervoerder + nummer) wanneer die beschikbaar is.
• Persistentie — het gesprek blijft 7 dagen bewaard bij een paginaverversing, en een Start over-knop wist het om opnieuw te beginnen.

Maten, kleuren en kits

Sinds 2.2.0 accepteert het winkelwagentje van de chat niet meer alleen eenvoudige producten. Heeft een product keuzes, dan biedt de assistent ze één voor één in het gesprek aan, en het product gaat met de juiste variant naar het winkelwagentje.

• Configureerbaar — eerst de maat, dan de kleur, dan het aantal, in de volgorde waarin u de attributen in Magento hebt ingesteld. Niet-bestaande combinaties worden nooit aangeboden.
• Gegroepeerd (kits) — alle artikelen in één keer, elk met zijn eigen aantal; wat op nul blijft, komt niet in het winkelwagentje.
• Bundel (samenstellingen) — één keuze per optie, optionele onderdelen inbegrepen.

De keuzes worden getekend zoals u ze in Magento hebt ingesteld: kleuren met hun echte hexcode, maten groot en leesbaar, lange lijsten als dropdown. Het aantal verschijnt op de laatste kaart. Op de desktop gebeurt alles in het zijpaneel, op de telefoon in de chat. Op bundel- en groepskaarten staat de echte prijsrange, niet € 0,00.

Uitverkochte opties blijven zichtbaar, uitgegrijsd. Dat is de standaard: een uitverkochte maat verbergen laat de klant geloven dat u die niet maakt. De schakelaar staat in Stores → Configuration → Codingrow → AI Personal Shopper → Catalog Search → Show unavailable choices, greyed out; opties die nog besteld kunnen worden, worden nooit uitgegrijsd. Niet te verwarren met Only in-stock products, dat bepaalt of het product überhaupt wordt voorgesteld.

Heeft een product aangepaste opties die de chat niet aankan (een gravure om in te typen, een bestand om te uploaden), dan zegt de assistent dat en biedt de link naar de productpagina aan, in plaats van zwijgend een pagina te openen.

Sessies en paginabewustzijn

De assistent houdt bij met wie hij praat en waar, zodat het gesprek continu aanvoelt en bij het juiste product blijft.

• Toegangsritueel — in plaats van een direct standaardantwoord toont de widget kort Connecting…, waarna een medewerker met een naam na 10–20s "aan de chat deelneemt" en om de naam van de klant vraagt. De timing en het typen zijn gesimuleerd, en het tempo is instelbaar.
• Sessies — komt de klant na meer dan ~5 minuten terug, dan start een nieuwe sessie zonder opnieuw om de naam te vragen, gemarkeerd door een scheidingslijn in de chat; binnen enkele minuten gaat hij gewoon door.
• Productpaginacontext — wanneer de chat wordt geopend vanaf een productpagina, wordt een impliciete vraag ("vertel me erover", "waar is het van gemaakt?") opgelost naar dat product, native gekoppeld via URL/url_key en bestand tegen omleidingen.
• Winkelwagenbewustzijn — via get_cart kan de assistent wat al in de winkelwagen zit meenemen als signaal van interesse — om passende suggesties te doen en niet opnieuw voor te stellen wat er al in zit — zonder erover te becommentariëren.
• Afsluitende cross-sell — wanneer de capability is ingeschakeld en de klant klaar is, voegt hij een of twee aanvullende producten toe als laatste suggestie en neemt dan afscheid.

Proactieve assistent

Sinds 2.2.0 kan de assistent het initiatief nemen. Dit stelt u in via Stores → Configuration → Codingrow → AI Personal Shopper → Proactive assistant, en in het begin staat alles uit: een verkoper die als eerste spreekt verkoopt meer of irriteert, en hoe u met uw klanten praat weet alleen u. Het chatvenster gaat in geen geval vanzelf open: de assistent laat het stipje op de knop oplichten en wacht.

• Suggest pairings after an add to cart — Never (standaard), only the first time in a visit of every time. Legt de klant tijdens het rondkijken iets in het winkelwagentje, dan bereidt de assistent een paar combinaties voor. Elke keer is dat één AI-aanroep, gefactureerd door uw provider. Er is hier geen wachttijd: het start meteen en verschijnt zodra het model antwoordt.
• Offer help after (seconds on the page) — 0 = nooit (standaard). Staat een klant zo lang op een pagina zonder de chat ooit te openen, dan wordt hulp aangeboden. Dat kost niets: de zin wordt door de widget geschreven. Nooit in het winkelwagentje of de checkout.
• What it says — de tekst van de uitnodiging. Leeg = standaardzin, vertaald in alle talen van de module.

Werkt zowel op Hyvä als op Luma: de widget luistert naar de gebeurtenissen die het thema al afvuurt wanneer het winkelwagentje verandert, dus ook een AJAX-toevoeging zonder paginaherlaad wordt opgemerkt.

Zo ontstane gesprekken slaan het naamritueel over en komen zonder naam in Conversations terecht: u herkent ze aan de kolom Origin (Customer, Assistant — after an add to cart, Assistant — offered help). Antwoordt de klant en noemt hij zijn naam, dan wordt die net als in elke andere chat vastgelegd.

Branding en kleuren

Stel een Assistant name in (wordt getoond als de naam van de medewerker, bijv. "Anna") en optioneel een Brand logo (vaste hoogte, zodat het nooit vervormt) of een Brand text met je bedrijfsnaam — beide worden linksboven in de chatheader getoond. De naam van de medewerker blijft zichtbaar als subregel met een live aanwezigheidspuntje onder het merk, ook als er een logo is ingesteld. Accent color bepaalt de openingsknop en de accenten in de chat; Header/theme color (optioneel) kleurt de headerbalk en de berichtenbubbels van de klant — laat leeg om de accent color te hergebruiken.

AI-zoekknop

Wanneer de vaste zoekbalk van de Live Search-module actief is, kan de AI Personal Shopper een tweede AI-loepknop vlak naast het zoekveld toevoegen. Erop klikken opent de assistent-chat; en als de klant al iets in het zoekveld heeft getypt, wordt die tekst meteen als eerste bericht verzonden — zo wordt een zoekopdracht met te veel (of nul) resultaten met een tik een begeleid gesprek.

Schakel hem in onder Stores → Configuration → Codingrow → AI Personal Shopper → Assistant & Branding met AI button in the search bar = Yes. Het is een zachte integratie: als Live Search niet is geinstalleerd of de vaste balk uit staat, verschijnt de knop simpelweg niet — geen harde afhankelijkheid.

Zelflerende synoniemen

Indien ingeschakeld (Capabilities → Self-learning synonyms), legt de agent een koppeling vast telkens wanneer het zoekwoord van een klant niet rechtstreeks overeenkomt met de catalogus, maar een latere poging wel — regionale namen, dialect, typefouten, synoniemen. Bekijk en bewerk het register bij Codingrow → AI Personal Shopper → Synonyms: een gepagineerde, inline bewerkbare tabel. Gebruik Export CSV / Import CSV om het te back-uppen, in bulk te bewerken of tussen omgevingen te verplaatsen. De knop Inject into site search zet het hele register over naar de native Search Synonyms van Magento, zodat ook de zoekbalk van de site ervan profiteert — niet alleen de chat. De agent leest ook je handmatig samengestelde native Search Synonyms, zodat beide systemen elkaar versterken.

Voorbeeld: een klant zoekt op "hoodie met capuchon" en de agent vindt direct niets, maar een latere poging met "hoodie" komt wel overeen — het paar wordt automatisch vastgelegd, zodat de volgende zoekopdracht naar "hoodie met capuchon" meteen wordt opgelost, en je kunt het met één klik in de native zoekfunctie invoeren.

Tickets voor menselijke ondersteuning

Indien ingeschakeld (Capabilities → Human support tickets), stelt de agent voor een ticket te openen als een klant een mens nodig heeft en het gesprek alleen het probleem niet oplost. Hij vraagt om e-mail (verplicht) en, indien nuttig, een bestelnummer en een telefoon-/WhatsApp-contact, en kent dan een ticketnummer toe — voorafgegaan door Ticket number prefix (standaard AIPS-), bijv. AIPS-000042 — en stuurt de klant per e-mail de volledige transcriptie, met BCC naar het adres ingesteld bij Human support → Support email (BCC) (blijft dit leeg, dan gaat de e-mail alleen naar de klant). De aan de klant getoonde reactietijdtekst komt uit Human support → Response time.

Tickets verschijnen onder het tabblad Tickets & Support: een tabel met View die de contactgegevens en volledige transcriptie opent, en een kolom Closed by die vastlegt wie elk ticket heeft gesloten — admin, cron of customer. De actie Resolve sluit een ticket en kan de standaard sluitingsmelding voor dat ticket overschrijven door de klant een aangepast bericht te sturen. Een dagelijkse taak sluit automatisch elk ticket dat langer openstaat dan Auto-close open tickets after (days) (vastgelegd als closed_by = cron). De klant kan zijn eigen ticket ook vanuit de chat sluiten of annuleren, maar alleen na een eigendomscontrole — het ticketnummer én de e-mail moeten overeenkomen. De agent classificeert gesprekken die een siteprobleem melden bovendien als Bug report, zodat problemen je team bereiken zonder een supportticket.

Voorbeeld: een klant schrijft "Ik moet met iemand praten over mijn bestelling". De agent vraagt om zijn e-mail (en, indien nuttig, het bestelnummer en een telefoon-/WhatsApp-contact), kent een ticketnummer toe zoals AIPS-000042 en stuurt de klant per e-mail de volledige transcriptie, met BCC naar je supportadres. Je team lost het op vanuit het tabblad Tickets & Support — optioneel met een aangepast bericht aan de klant — of het sluit automatisch (closed_by = cron) nadat het het ingestelde aantal dagen inactief is geweest.

Beveiliging en misbruikpreventie

Omdat elk AI-antwoord een echte API-aanroep kost, wordt de widget beschermd door een gelaagde verdediging die probes, scanners, injectie- en prompt-injectiepogingen en berichten met weinig waarde tegenhoudt voordat ze ooit het model bereiken — kosteloos.

• Limieten per IP — een burstlimiet van 15 verzoeken / 60s, 300 verzoeken per dag, maximaal 30 nieuwe chats per dag en 60 beurten per gesprek.
• Globale circuit breaker — een winkelbreed plafond van ongeveer 5.000 AI-aanroepen per dag beschermt het budget tegen een gedistribueerde aanval.
• Widget-bewijstoken — de widget bewijst dat hij het echte toegangsritueel heeft doorlopen; de schakelaar Require widget token (Security & anti-abuse) dwingt dit af en weigert vervalste aanroepen aan het endpoint.
• Volledige logging — elke geblokkeerde gebeurtenis wordt gelogd met IP, user-agent en reden, zodat misbruik zichtbaar blijft.
• Provider-watchdog — begint de AI-provider te falen (geen krediet, verkeerde sleutel), dan stuurt een watchdog je een e-mail zodat een stille storing niet onopgemerkt blijft.

Gesprekken lezen

Codingrow → AI Personal Shopper → Conversations toont elk gesprek, automatisch geclassificeerd als Shopping, Support, Bug report, Possible spam of Other, gepagineerd en filterbaar per type. De actie View opent de volledige thread — elk bericht van klant en assistent, inclusief de productkaarten die bij elke beurt werden voorgesteld — alleen-lezen. Gesprekken kunnen afzonderlijk of in bulk worden verwijderd; oudere gesprekken die de ingestelde bewaartermijn overschrijden, worden verwijderd door een dagelijkse taak (bugmeldingen zijn uitgesloten van automatische opschoning).

Voorbeeld: een gesprek waarin de klant een fout bij het afrekenen beschrijft, wordt automatisch ondergebracht bij Bug report, zodat je team het in de console ziet zonder dat iemand een e-mail hoeft te sturen.

Licentie

De licentie wordt uitgegeven voor één domein en kan een losse module-sleutel (AI Personal Shopper) of een Codingrow-abonnementssleutel (alle modules) zijn. Zonder geldige licentie wordt de chatwidget niet weergegeven. Je licentie dekt de huidige versie plus 1 jaar updates en support; je kunt de gedekte versies voor altijd blijven gebruiken en de support (−35%) verlengen om naar nieuwere versies te upgraden.