AI Personal Shopper Documentation

Installation

Requirements

Magento 2.4.x — tested on 2.4.9, compatible with previous 2.4.* releases. PHP 8.1–8.5. Compatible with both the default Luma theme and the Hyvä theme (the chat widget renders in an isolated Shadow DOM, so it looks identical on both, with no template changes). Depends on the free codingrow/module-core module, installed automatically. Requires an API key from at least one AI provider (OpenAI, Anthropic, Google or OpenRouter) — billed to you directly by the provider.

Setup steps

1. Add the credentials you'll receive by email to auth.json in your Magento project root:

   { "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. Paste your license key into Admin → Stores → Configuration → Codingrow → AI Personal Shopper → License → License Key, save, then bin/magento cache:flush.

Configuration

Open Admin → Stores → Configuration → Codingrow → AI Personal Shopper. Enter your License Key, set Enable to Yes, choose your AI Provider and paste its API key, then review Capabilities.

Uninstallation

Set Enable to No and save to hide the widget immediately. To remove the module entirely: bin/magento module:disable Codingrow_AiPersonalShopper then composer remove codingrow/module-ai-personal-shopper.

AI provider setup

Choosing a provider

The assistant works with any of four providers — you bring your own API key, and the AI usage is billed to you directly by the provider you pick. OpenAI (ChatGPT/GPT) offers the broadest lineup; Anthropic (Claude) is a strong fit for an assistant that must stay on-script; Google (Gemini) is competitively priced and fast; OpenRouter gives you one key for dozens of models across providers, handy for comparing cost and quality.

Getting an OpenAI API key

1. Sign in at platform.openai.com.
2. Go to platform.openai.com/api-keys.
3. Click Create new secret key, name it (e.g. "AI Personal Shopper"), and copy it immediately — it is shown only once.
4. Paste it into AI Provider → API Key with Provider set to OpenAI, then use Load models.

Getting an Anthropic API key

1. Sign in at console.anthropic.com.
2. Go to console.anthropic.com/settings/keys.
3. Click Create Key, name it, and copy the value.
4. Paste it into AI Provider → API Key with Provider set to Anthropic, then use Load models.

Getting a Google API key

1. Sign in at aistudio.google.com with a Google account.
2. Go to aistudio.google.com/app/apikey.
3. Click Create API key, choose or create a Google Cloud project, and copy the key.
4. Paste it into AI Provider → API Key with Provider set to Google, then use Load models.

Getting an OpenRouter API key

1. Sign in at openrouter.ai.
2. Go to openrouter.ai/keys.
3. Click Create Key, name it, and copy the value.
4. Paste it into AI Provider → API Key with Provider set to OpenRouter, then use Load models.

Load models

Once the API key is in place, click Load models under the Model field: the module calls the provider's own model-list endpoint with your key and fills a dropdown with every model your key can actually use — pick from the list instead of typing an id. A manual text input remains available as a fallback for a model id not yet in the list. A link right below the field always points to the correct key page for whichever provider is currently selected.

User guide

Capabilities

Each capability is an independent toggle under AI Provider & Capabilities: product search, order status lookup, promotions, add-to-cart, voice input, self-learning synonyms, human support tickets. Turning a capability off removes that ability from the agent immediately — for example, disabling Human support tickets means the agent will never propose opening a ticket.

Branding and colors

Set an Assistant name (shown as the operator, e.g. "Anna") and, optionally, a Brand logo (fixed height so it never deforms) or Brand text with your company name — shown top-left in the chat header. The operator name still appears as a sub-line with a live presence dot underneath the brand, even when a logo is set. Accent color controls the launcher button and in-chat accents; Header/theme color (optional) colors the header bar and the customer's message bubbles — leave it empty to reuse the accent color.

Self-learning synonyms

When enabled (Capabilities → Self-learning synonyms), the agent records a mapping every time a customer's search word doesn't match the catalog directly but a later attempt does — regional names, dialect, misspellings, synonyms. Review and edit the registry in Codingrow → AI Personal Shopper → Synonyms: a paginated, inline-editable table. Use Export CSV / Import CSV to back it up, bulk-edit it, or move it between environments. The Inject into site search button writes the whole registry into Magento's native Search Synonyms, so the storefront search bar benefits too — not just the chat. The agent also reads your hand-curated native Search Synonyms, so both systems reinforce each other.

Human support tickets

When enabled (Capabilities → Human support tickets), the agent proposes opening a ticket if a customer needs a human and isn't resolved by the conversation alone. It asks for email (required) and, when useful, order number and a phone/WhatsApp contact, then assigns a ticket number and emails the full transcript to the customer, BCC'd to the address set in Human support → Support email (BCC) (if left empty, the email goes only to the customer). The response time text shown to the customer comes from Human support → Response time. Tickets appear under the Tickets & Support tab: a grid with View opening the contact details and full transcript, a mark-resolved action (with an optional notification email), and automatic auto-close after the configured number of days. The agent also classifies conversations that report a site problem as Bug report, so issues reach your team without a support ticket.

Reading conversations

Codingrow → AI Personal Shopper → Conversations lists every conversation, automatically classified as Shopping, Support, Bug report, Possible spam or Other, paginated and filterable by type. The View action opens the full thread — every customer and assistant message, including the product cards proposed at each turn — read-only. Conversations can be deleted individually or in bulk; older conversations beyond the configured retention are purged by a daily task (bug reports are excluded from automatic purging).

License

The license is issued for one domain and can be a single-module key (AI Personal Shopper) or a Codingrow subscription key (all modules). Without a valid license the chat widget does not render. Updates are included within the same major version.