> For the complete documentation index, see [llms.txt](https://docs.codegiganten.de/plugin-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/shopping-assistant.md).

# Shopping assistant (beta)

The shopping assistant (beta) advises customers in your shop with a few questions and shows the best matching products with a short reason.

The shopping assistant advises your customers like a sales person in a store. Customers describe in their own words what they are looking for. The assistant detects category, attributes and price range, asks only what is still missing, and finally shows the best products with a short reason.

This page describes what your customers experience, how to join the beta, and how to set up and evaluate the assistant. The assistant is a **beta feature**: it is free of charge, and features and limits may still change.

{% hint style="info" %}
The assistant does not replace the search. It is an additional way for customers who are not sure how to search. The search keeps working as usual, even when the assistant is not visible.
{% endhint %}

## What your customer experiences

### The button

A round button appears fixed at the bottom edge of the screen, bottom right by default. The default label is "Advice". You set position and label in the plugin dashboard (see [Setup](#setup)).

The button only appears if all of these conditions are met:

* The InsightSearch search is active for the sales channel.
* "Show the shopping assistant in the shop" is switched on for the sales channel (default: off).
* Your account is enabled for the beta and the trial is running.
* The page is neither the cart nor a checkout page. The assistant never appears there, and this cannot be changed.

When the trial ends or the quota is used up, the button disappears without a notice. Changes take effect in the shop with a delay of up to one minute.

### The window

On a computer, a side panel opens over the full height, on the same side as the button. On a phone (below 768 pixels width) it fills the whole screen. While it is open, the button is hidden.

The header shows the name of the assistant (default "Shopping assistant") and three icons: restart, minimize and close. Minimize and close both hide the window, and the conversation is kept. At the bottom there are the "Back" button, the input field (up to 300 characters) and "Send".

As accent colour the assistant uses the colour set in the "Shopping assistant" area, otherwise the accent colour of the search, otherwise a default blue.

### Course of a conversation

1. **Greeting.** The window shows a greeting and selection buttons, the entry points. If you have not created your own, the assistant builds some itself: the four most frequent categories and a "Get advice" button. On a category page the conversation starts with that category.
2. **Free text.** The customer writes in their own words, for example category, brand, attributes or price range. An AI translates this into filters. Only values that really exist in your product data are used. The rest of the sentence is used as a normal search text. Prices, availability and product data always come from the search, never from the language model.
3. **Questions.** The assistant only asks about attributes that are still missing and that you have allowed. Each question offers up to five answer buttons with the most results and a "Doesn't matter" button. For numbers and prices, two to three ranges are offered. **At most four questions** per conversation.
4. **Interim result.** After each step the assistant shows a swipeable row of matching products with image, name and price, plus "N matching products" and the link "Show all N", which opens the search results page.
5. **Conclusion.** The conversation ends as soon as six or fewer results are left, no useful question remains, or the limits are reached (four questions or eight steps). The assistant then shows the three best products. Each product has a short reason put together from the attributes the customer chose, for example "Trail · waterproof". If the customer chose no attribute, there is no reason.

The order of questions follows your settings: filters you marked "Ask first" come first, then your filter order, then a score for purchase relevance (category, brand and colour before technical values such as weight or dimensions). Filters that concern too few of the current results, or have fewer than two values with results, are skipped.

The question text is either your own (own question), or a short text written by the AI in the language and form of address of the shop, or a fixed fallback text.

### When nothing is found

If there are zero results, the assistant loosens the search by itself and says so openly. First it widens a price limit, then it drops the attribute chosen last. The customer is told what was changed. If there are still zero results, the assistant asks the customer to describe the wish differently.

### Back, restart and follow-up

* **Back** undoes the last answer and asks the previous question again. The button is only active once the customer has answered something.
* **Restart** begins a new conversation. It counts as a new conversation in the quota.
* The customer can add free text at any time and so change the search.
* For off-topic input, the assistant replies that it helps with product search. For questions about orders, delivery or returns it refers to the customer account.
* The assistant only advises on products. It does not answer questions about single products, does not compare products and does not hold free chat.

### Continuing

If the customer clicks a product and comes back, the conversation can continue. It is remembered in the browser tab, not across tabs, and kept on our side for 30 minutes without activity. After that, a new conversation begins.

If the assistant cannot be reached in the middle of a conversation, "The assistant is currently not available." appears with a link "To search".

### Entry from the search window

The search window shows a note with a button: "Our assistant helps you with a few questions." and "Get advice". It appears

* when the search returns no results (also next to the CMS page for searches without results), or
* when the search text is a whole sentence, that is four words or more.

A click closes the search window, opens the assistant and takes over the search text as the first input. This is a new conversation. You can switch the note off with "Offer "Get advice" in the search overlay (no results or longer sentences)" (default: on).

### Language and form of address

The language follows the language of the shop. Fixed texts exist in German and English. You set the form of address per sales channel to informal "du" (default) or formal "Sie". It applies to all fixed texts, the note in the search window and the AI questions. In English there is no difference. You maintain button text, name and greeting per language yourself.

### Keyboard and phone

* Everything can be used with the keyboard. The Escape key closes the window.
* On opening, the cursor jumps into the input field, on closing back to the button.
* New messages are announced to screen readers. The window is a labelled dialog.
* On a phone, the assistant opens in full screen and the button sits slightly lower. There is no separate phone design as there is for the search.

## Join the beta

The assistant is not available to every account automatically. You apply for the beta.

1. Open the area **Shopping assistant** in the plugin dashboard. Without approval you see an introduction with the sections "How it advises", "What you control" and "Privacy".
2. If you like, write in the field "What do you expect from the assistant? (optional)" (up to 1000 characters) what you expect.
3. Tick "I have read and accept the beta terms." Use "Read terms" to open the terms.
4. Click **Join the beta**.

You need the "edit settings" permission to join. The approval applies to your InsightSearch account, not to single Shopware users.

### What is sent along

Sent automatically: shop URL, Shopware and plugin version, number of products, languages, and the name and email address of your admin user. The form states this as well.

### Beta terms in short

* The beta is free. We will inform you in good time before any later charge; there is no automatic charge.
* Features, texts and limits may change, outages are possible.
* Conversations are analysed anonymously to improve questions and results. Inputs are masked and deleted after 30 days.
* You can switch the assistant off at any time, and we may end the participation.
* We contact you by email at the address of your Shopware user.

### Status messages

| Display in the area                   | Meaning                                                                                                                                                        |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Request received"                    | We are reviewing your request and will contact you by email.                                                                                                   |
| "Request not possible yet"            | The request was declined. You see the reason and the date from which a new request is possible (30 days after the decline). After that the form appears again. |
| Settings and button "Try it for free" | Your account is enabled.                                                                                                                                       |

An account can only have one open request. On approval you receive an email with the subject "Du bist in der Beta des Shopping-Assistenten", on rejection an email with the reason.

## Trial

After approval you start the trial with **Try it for free**: **100 conversations or 14 days**, whichever comes first. Only now are all settings unlocked. Before that they are visible but locked ("The settings are locked until the trial is running.").

The area shows the current status, for example "Trial: 12 of 100 conversations, 9 days left", with a progress bar.

### Only once per shop

The trial is available once per shop. When it has been used, you see "The trial has already been used for this shop."

### What counts as a conversation

* A conversation counts only once the customer answers for the first time, using an answer button, an entry button or free text. Just opening and closing does not count.
* A conversation that starts on a category page counts as soon as it continues.
* "Restart" counts as a new conversation. A conversation ends after 30 minutes without activity.
* Double clicks or two tabs do not count twice.
* "AI suggestions" in the admin do not count.

{% hint style="info" %}
The analytics count conversations only from the customer's first own input. They can therefore be lower than the trial usage.
{% endhint %}

### What happens when it is used up

* **100 conversations used:** The button disappears for new conversations. Conversations already started may be finished.
* **14 days over:** The assistant disappears, and running conversations are ended too.
* In both cases the area says "Trial ended. Packages will follow after the beta." and the settings are locked again. The search keeps working as usual.

## Setup

You find all settings in the plugin dashboard in the area **Shopping assistant**. They apply only after **Save** at the end of the page ("Assistant settings saved.").

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-83e2eef751a7d61e66e45ac5dea221b0f060fde6%2Fsuche-intelligent-und-ki-optimiert-shopping-assistent.png?alt=media" alt="Shopping assistant area with trial usage, Display card and Texts card"><figcaption></figcaption></figure>

### Display

Applies per sales channel. The value of a channel overrides "All sales channels", empty fields inherit.

| Setting                                                                     | Effect                                                                             | Default      |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------ |
| "Show the shopping assistant in the shop"                                   | Switches the assistant on in the channel.                                          | off          |
| "Button position"                                                           | "Bottom right" or "Bottom left".                                                   | Bottom right |
| "Form of address"                                                           | "Informal (du)" or "Formal (Sie)".                                                 | du           |
| "Offer "Get advice" in the search overlay (no results or longer sentences)" | Shows the note in the search window.                                               | on           |
| "Accent colour"                                                             | Colour of the button and the selection buttons. Empty means: colour of the search. | empty        |

### Texts

Applies per sales channel **and** language. Choose the "Language" at the top.

| Field                   | Limit                                       | Default text                      |
| ----------------------- | ------------------------------------------- | --------------------------------- |
| "Button text"           | 60 characters                               | "Advice"                          |
| "Name of the assistant" | 60 characters                               | "Shopping assistant"              |
| "Greeting"              | 500 characters (longer texts are shortened) | Default greeting of the assistant |

Empty fields use the value from "All sales channels", otherwise the default text. A custom greeting replaces only the first message, not later questions. Fixed built-in texts such as the placeholder in the input field and the button names cannot be changed.

### Entry points and questions

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-3af09c01575a24667296a410272e406cb81f3969%2Fsuche-intelligent-und-ki-optimiert-shopping-assistent-einstiege.png?alt=media" alt="Cards Entry points and Questions, AI suggestions, six entry points with text and search text, and allowed questions"><figcaption></figcaption></figure>

Entry points and questions apply per index, that is per sales channel and language. Choose the index with "Choose product feed".

**Entry points.** Up to six selection buttons in the greeting, for example "Find running shoes".

| Field            | Limit                                |
| ---------------- | ------------------------------------ |
| "Text"           | 40 characters                        |
| "Category"       | Choice from your Shopware categories |
| "or search text" | 120 characters                       |

Every entry point needs a category or a search text, otherwise it cannot be saved. "Add entry point" creates more, "Delete" removes one.

**Questions.** There is one row for every active filter of the index:

| Setting                   | Effect                                                                                     | Default |
| ------------------------- | ------------------------------------------------------------------------------------------ | ------- |
| "May be asked"            | Off means: the assistant never asks about this filter, and the AI does not see the filter. | allowed |
| "Ask first"               | The filter comes before the others. Only available if it may be asked.                     | off     |
| "Own question (optional)" | Your text instead of the AI text, 120 characters.                                          | empty   |

If the index has no active filters, you see "There are no active filters for this index."

### AI suggestions

With **Generate suggestions** you set up entry points and questions in a few minutes. The AI suggests:

* entry points,
* question texts, in the language of the index and the chosen form of address,
* which filters may be asked and which come first.

The result appears in two lists. With "Take" per row or "Take all" you fill the form. Nothing is saved until you click "Save". Review the suggestions before saving. The AI never overwrites your own question texts unasked.

**Which data goes to the language model?** For the suggestions, filter names and the most frequent filter values, category names and titles of sample products of the index are sent to the language model. The processing runs in data centres in Germany.

**Daily limit:** at most 10 runs per day. After that you see "The daily limit for suggestions has been reached. Try again tomorrow." If a run is already in progress, please wait a moment.

**Index without filters:** If the index has no active filter yet, the AI first creates up to six filters from your data attributes. These are only attributes with at least two different values, no technical fields such as numbers, prices in cents, stock or links. These filters are visible in the assistant only and carry the label "assistant only". You edit them in the "Filter" tab. This counts as one run of the daily limit.

### Filters "assistant only"

In the "Filter" tab, the edit dialog has the switch "Show in search" (default: on). If you switch it off, only the assistant uses this filter. It then does not appear in the search window, on the search results page or on category pages, and it is not set automatically from the search text. This suits attributes such as purpose of use or fit. If a filter is inactive, the assistant does not use it either.

### So the assistant asks good questions

* Create active filters. Without filters only free text and categories remain.
* Keep the values clean and separate in the data attribute. If "Blue, Red, Green" is one value in the field, the answer buttons will be poor.
* A filter is only asked if at least two values have results and a sufficient part of the current results has a value at all.
* Price and list filters such as brand, colour or purpose come early. Numeric values such as weight or dimensions come late or almost never.
* The assistant offers only specific subcategories, not the top level. Meaningful category names help.
* Values are shown exactly as in the product data. Values that every product has are not offered.
* Keep your own question texts short.
* The analytics show which questions are often abandoned.

## Analytics

You see the card "Assistant analytics" if your user may view orders (permission "Orders: View"). At the top you choose the period: 7, 30 or 90 days.

* **Key figures:** "Conversations" and "Click rate". If order data is available, also "Carts", "Orders" and "Revenue from chat".
* **"From conversation to order":** from the start through answered question, shown result and product click to cart and order.
* **"Conversations per day".**
* **"Questions that are often abandoned":** table with "Asked", "Abandoned" and "Doesn't matter", only for questions asked at least 10 times. "Adjust question text" jumps to the question text field.
* **"Frequent wishes without matching products":** free texts without results, only from three identical inputs.
* **"Requested attributes" and "Attributes that do not exist in the shop".**
* **"Entry points":** where the conversations come from, such as free input, entry button, category page or search page.
* **"Products in the assistant" and "Often shown, never clicked".**

A purchase counts for the assistant per purchased product if that product was clicked in the assistant. Up to 72 hours may pass between click and order, in the same browser. Order data appears only if tracking delivers it.

For privacy reasons we do not show single conversations, and wishes only from three identical inputs.

## Data protection

* The language processing runs in data centres in Germany.
* Only typed text is stored, without IP address and without customer identifier. Clicks on selection buttons are not stored as text.
* Before storing, email addresses, phone numbers, IBANs and long digit sequences are masked.
* Conversations are deleted after 30 days.

{% hint style="warning" %}
The masking covers the patterns named above. It does not recognise names or addresses in free text. Include the assistant in your privacy notice.
{% endhint %}

## Further reading

{% content-ref url="/pages/FhhERjHQ8jiFPqUQjjHW" %}
[Data protection](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/data-protection.md)
{% endcontent-ref %}

{% content-ref url="/pages/YEBvytB69E4Y4qAMmqvE" %}
[Filters](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/filters.md)
{% endcontent-ref %}

{% content-ref url="/pages/UbPgPTIvpH80zt0F5BMB" %}
[Permissions](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/permissions.md)
{% endcontent-ref %}

{% content-ref url="/pages/wSe62PjPXaI2JZoT2rqj" %}
[Feedback, support and cogi Commander](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/feedback-and-commander.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/shopping-assistant.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
