This manual walks you through setting up the AI-powered pre-sales chat, connecting an AI provider and tailoring the advice to your catalog.
Shopware 6.7 and an API key with one of the four supported AI providers: OpenAI, Anthropic (Claude), Mistral or Google Gemini. Automatic log cleanup requires a running worker.
Install it in the admin under Extensions, My Extensions, Upload - or place the plugin folder in custom/plugins/StawKiProductAdvisor and install it from the console:
In the admin under Marketing, AI Product Advisor: activate it, choose the provider and store the API key. Each provider keeps its own key and model, so you can switch providers without losing keys. Every setting can be configured per sales channel.
The product advisor is a pre-sales chat in the storefront. It answers customer questions and recommends matching products. The reply is streamed via server-sent events, so it appears progressively rather than all at once, optionally with a typing effect.
Every query first searches the catalog. The AI may then only recommend from those matches. That rules out invented products which do not exist in the shop - the most common complaint about AI chats in retail.
A fast preliminary call extracts search terms plus price and property constraints such as colour, material or size from the customer question. If that call fails, a local fallback takes over. The timeout is 10 seconds so the chat never hangs. The model used for this extraction can be chosen separately from the answering model.
At the top of the module you choose sales channel and language. Every setting applies to all channels first; select one and it gets its own values.
The settings are grouped into collapsible areas and start closed. Each header has the title on the left and the chevron on the right; the explanation sits in the info icon behind the title.
Reorganised: Behaviour now only holds role, master prompt, search and answer behaviour. Everything the customer sees in the chat window is in Chat interface. The privacy notice has an area of its own.
The advisor takes the cross-selling assignments maintained in Shopware into account: for the best matches, the linked partner products are actively included in the recommendation and marked as "goes well with".
Recommendations and product cards are ordered by how well they fit the question, and related products are presented together rather than scattered across the answer.
Filled custom fields enter the context passed to the AI, with language-correct labels. A multi-select in the settings lets you decide which fields are included - with no selection, all of them are.
In the chat detail window the values appear as a separate "More details" section. If the fields contain links or embedded videos, those are clickable and open in a window of their own.
Besides product data, the advisor can read content from your shop pages. How much text is considered per page is set in the "Character limit per shop page" field.
A value of zero means unlimited. The recommendation is 4,000 to 8,000 characters per page - enough for a typical guide page without flooding the context with peripheral text.
Recommended products appear directly in the chat as a quickview. For variant articles a configurator is built in: the selection resolves the matching variant, so the cart and product links point at that exact variant rather than the parent article.
Optionally the chat opens by itself after a configurable delay. The button can also pulse to draw attention. Both can be switched off.
For every recommendation the plugin records clicks, cart adds and cart value. That makes it possible to quantify what the advisor actually contributes to revenue rather than only showing conversation counts.
The statistics view in the admin shows the most frequent search terms and the most recommended products. The raw data can be exported as CSV for further processing.
What gets transmitted is the customer message text including the session conversation so far, plus a compact excerpt of matching catalog products, meaning name, number, price and properties. Order, account and payment data are not transmitted.
E-mail addresses and phone numbers are removed automatically before anything goes to the provider. On top of that you can enable a consent gate that requires confirmation before the first message.
With logging enabled the plugin stores anonymised queries without e-mail or phone number. You set the retention period in days and a daily task deletes older entries. The task needs an active worker.
Check whether the advisor is active in that sales channel - settings apply per channel. Then clear the cache.
Usually a valid API key for the chosen provider is missing, or the model is not enabled for that key. Smart search times out after 10 seconds and falls back to local search.
The advisor can only recommend what the catalog search finds. Check product names and properties, and sharpen the persona.
The cleanup task only runs with an active worker.
If you have questions about setup, choosing a provider or data protection, we are happy to help. Get in touch via the contact page or write to info@stoneandwater.online.
Every setting of the plugin with its default value and explanation, in the same order as in the administration. The texts come straight from the plugin (version 1.8.25).
License for the direct-sale edition of this plugin.
The licence key from your Stone & Water customer account. Without a valid licence the advisor stays locked.
Switches the advisor in the shop on or off.
The service that writes the answers: OpenAI, Anthropic, Mistral or Google. The chosen provider gets its own API key.
Access key of the chosen provider. Each provider has its own field.
The language model of the chosen provider. Without a selection the advisor uses the provider's default model.
Only required when the API key is not scoped to a workspace - the Anthropic API then requires the workspace ID (wrkspc_...). Alternatively create a workspace-scoped key in the Anthropic console.
Name, avatar and tone of the advisor.
Tone, expertise, cross-selling hints. Appended to the system prompt.
Your own ground rules for tone, approach and conversation flow. Applies in addition to the role above and takes effect in every conversation. The safety rules of the plugin (only recommend existing products, no invented details) remain untouched.
How many matching products are given to the AI as a basis for each answer.
Maximum length of a customer message in characters. Longer messages are shortened to this length.
Only recommends products that are currently available.
Prefers well-selling products over slow movers when relevance is equal (light bestseller bonus in ranking).
Recommend directly: the very first answer already contains matching product cards (plus an optional refinement question). Advisory funnel: for broad requests the advisor first asks 1-2 targeted questions, then recommends.
Uses a fast pre-call to extract search keywords from the customer question for more precise catalog search (with local fallback). Off: the raw question is searched directly.
If the customer names a property (e.g. colour, material, size) and no product matches it exactly, nothing is shown. Off: close alternatives are shown and the advisor points this out honestly.
Passes the accessories of the currently viewed product to the advisor so it can suggest fitting add-ons. Cross-selling links of the matched products are also actively taken into account and related products are presented together.
Shows tappable answer options (from the customer perspective) after each reply so the customer can continue without typing - generated by the AI to match the answer.
Optional fixed answer options from the customer perspective (one per line, max 4). Used only when the AI does not generate its own. Empty = AI suggestions only.
Name, avatar, greeting, quick start and everything the customer sees in the chat window.
Name under which the advisor appears in the chat.
The advisor's first message when the chat is opened.
Clickable suggestions shown when the chat opens - one per line (max 4). Empty = none.
Grey text in the chat input field. Empty = language dependent default text.
Answer appears smoothly character by character instead of in bursts.
How fast the typing effect reveals answers: slow, normal or fast.
Shows a category link under each recommendation (and in the detail modal) so customers can keep browsing.
Shows the variant picker (e.g. colour, size) as a styled dropdown in the detail modal. Off: the modal links to the product page for variant selection.
Automatically closes the detail modal once a product has been added to the cart successfully. The confirmation stays visible in the chat.
Shows an add-to-cart button directly on each recommendation card (products without variants only). Variant products still go through the detail modal.
After add to cart, shows fitting accessory cards from the cross-selling assignments of the product directly in the chat.
Shows a thumbs up/down after each answer. Ratings appear anonymously in the statistics (satisfaction).
On: clicking a recommendation opens a detail modal in the chat. Off: the card links straight to the product page.
Notice shown before the first message.
Blocks input until the customer accepts the notice.
Privacy notice in the chat. Empty = the built-in default notice is shown automatically (DE/EN); your own text overrides it. With required consent the customer must agree before the first message.
Answers about shipping, payment, returns or promotions - type freely or include categories.
Free text the advisor uses for questions about shipping, payment, returns or discounts.
Maximum characters read per shop page. 0 = unlimited (default). Recommendation: 4,000 - 8,000 characters per page usually work best for the advisor - covering the content while keeping token usage and response time low. With many pages, prefer 2,000 - 4,000.
Only ticked fields are sent to the AI and shown in chat. Untick fields you do not maintain.
Gives the AI the product image of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI the manufacturer of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI the price including list price of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI the properties of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI the variant options of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI the categories of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI the tags of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI the rating of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI EAN and manufacturer number of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI content and unit of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI dimensions and weight of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI the description of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Gives the AI the custom fields of the products and shows it on the cards and in the chat's detail view. Switched off, it is left out in both places.
Widget placement including pixel offset from the default position.
Where the advisor appears in the shop: on all pages or only on product pages.
Hides the advisor on the checkout pages (login, order overview, finish).
Corner or edge of the screen where the chat button sits: bottom, middle or top, each left, centre or right.
Defines where the opened chat window sits - independently of the chat bubble. Empty = aligned to the chat bubble as before.
Distance from the left/right screen edge.
Distance from the top/bottom edge. Increase to avoid back-to-top buttons.
Custom corner for phones. 'Same as desktop' inherits the desktop position.
Distance to the left or right edge on smartphones. Empty uses the desktop value.
Distance to the top or bottom edge on smartphones. Empty uses the desktop value.
Colour for the button, speech bubbles and highlights in the chat.
Automatically opens the chat after a few seconds (once per session) to engage visitors.
Wait time before auto-opening.
When auto-opening on product and category pages, the advisor greets with a fitting question about the viewed product or category.
Makes the chat button pulse subtly until it is opened the first time.
When disabled, a text is shown in the bubble instead of the logo.
Shown when the logo is hidden. Empty = language dependent default text (Product advice).
Background of the chat bubble. Empty = white.
Empty = accent colour.
How many messages a visitor may send within the time window. Counted per visitor session; after that they have to wait.
Length of the rate-limit time window in seconds.
Anonymised analysis of advisor requests.
Logs older than this many days are deleted automatically. 0 = unlimited.
Two routes, the same feature set - pick whichever suits your setup.
All prices net, plus VAT.
Download the free Plugin Suite and upload it in the admin, no SSH needed. It installs and updates the plugin with one click. You buy the licence directly from us, with an invoice from us and support straight from the developer.
Listed in the official Shopware Community Store. Installation and updates run through the plugin manager, billing through your Shopware account. Store conditions differ from ours.
See every feature on the product page. We are happy to help with setup and fine-tuning.