# AI Personal Shopper Documentation Installation steps and a complete reference for every setting, with concrete examples — the same level of detail our support uses to help customers. ## 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) — the AI usage is billed to you directly by the provider, Codingrow never marks it up. ### Setup steps 1. Add the credentials you'll receive by email to `auth.json` in your Magento project root: ```json { "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 && bin/magento cache:flush` 6. Paste your license key into **Admin → Stores → Configuration → Codingrow → AI Personal Shopper → License → License Key**, save, then flush the cache. ### Configuration **Stores → Configuration → Codingrow → AI Personal Shopper.** | Setting | What it does | Default | Notes | |---|---|---|---| | **License Key** | The license key issued for this domain. | — | Accepts a single-module key or a Codingrow subscription key. Without a valid license the chat widget does not render. | | **Enable** | Turns the chat widget on for the storefront. | No | Requires a valid license and at least one AI provider API key. | | **AI Provider** | Which provider serves the conversation (OpenAI, Anthropic, Google, OpenRouter), the model, and the API key. | — | Use the **Load models** button next to the Model field — see below. | | **Assistant & Branding** | Assistant/operator name, greeting, launcher label/position, accent color, header/theme color, company logo or name, extra tone-of-voice instructions. | — | The operator name still shows as a sub-line under your brand when a logo/company name is set. | | **Capabilities** | Toggles: product search, order status, promotions, add-to-cart, voice input, self-learning synonyms, human support tickets. | — | Disable anything you don't want the agent to do. | | **Catalog Search** | Max products per reply, in-stock only. | — | Keeps replies focused instead of dumping the whole catalog. | | **Human support** | Support email (BCC), response time text, ticket number prefix, auto-close after N days, notify customer on resolve. | 24-48 hours | Only used when the **Human support tickets** capability is on. | | **Privacy** | Conversation retention, in days. | — | Older conversations are purged by a daily task; bug reports are kept until removed manually. | ### 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`. ## Choosing an AI provider and getting an API key The assistant works with any of four providers — you bring your own key, and the AI usage is billed to you directly by the provider you pick. ### OpenAI (ChatGPT / GPT models) 1. Sign in at [platform.openai.com](https://platform.openai.com). 2. Go to **[platform.openai.com/api-keys](https://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**. ### Anthropic (Claude models) 1. Sign in at [console.anthropic.com](https://console.anthropic.com). 2. Go to **[console.anthropic.com/settings/keys](https://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**. ### Google (Gemini models) 1. Sign in at [aistudio.google.com](https://aistudio.google.com) with a Google account. 2. Go to **[aistudio.google.com/app/apikey](https://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**. ### OpenRouter (one key, many providers' models) 1. Sign in at [openrouter.ai](https://openrouter.ai). 2. Go to **[openrouter.ai/keys](https://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 — no model id to type After the API key is in place, save the section (or use the on-page action if available) and 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 that isn't in the list yet. 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, only **Self-learning synonyms** governs whether unmatched searches get recorded. ### 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, 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 from what the agent has learned — 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** (default "24-48 hours"). 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 back to the customer), and an automatic **auto-close** after the number of days set in **Human support → Auto-close after (days)**. The agent also classifies conversations that report a site problem as **Bug report**, so issues reach your team without a support ticket. | Setting | What it does | Default | |---|---|---| | **Support email (BCC)** | Address that receives a BCC copy of every ticket transcript email. | — (customer-only if empty) | | **Response time** | Text shown to the customer when a ticket is opened. | 24-48 hours | | **Ticket number prefix** | Prefix used when assigning ticket numbers. | — | | **Auto-close after (days)** | Tickets with no activity are closed automatically after this many days. | — | | **Notify customer on resolve** | Sends the customer an email when a ticket is marked resolved from the admin. | Off | ### 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. --- © Codingrow (a brand of Revera SRLS). Sold worldwide. Licensed per domain.