Feeding your Assistant: which content goes where

Your Sales Assistant only ever answers from your own store's data — your catalogue, your pages, and the documents you give it. It never makes facts up. That means the quality of its answers comes down to one thing: giving it the right content, in the right form.

The single most important rule is this: structured facts need a different source than prose. A plan-comparison table, a price list, or a size chart is not the same kind of content as a shipping policy or an About page — and feeding them the same way is the most common reason an assistant answers only half a question. This page explains the four ways content reaches the assistant, and which one to reach for.

This applies to the Sales Assistant extension. If you haven't installed it yet, see Installing and managing extensions.

The four sources

1. Product catalogue — automatic. Your products — names, prices, stock, and attributes — are read straight from Magento and searched live. There's nothing to set up; just keep your catalogue accurate and up to date. A few small choices in how your attributes are configured decide how well shoppers can narrow — see Getting the most from your catalogue below.
2. CMS pages & blocks — automatic, on by default. Your active CMS pages and static blocks (FAQ, shipping, returns, About, and so on) are indexed for you as knowledge. You can turn this on or off under Stores → Configuration → Services → Sales Assistant → Knowledge indexing. Magento's own system pages (such as no-route and enable-cookies) are always skipped.
3. File upload. Upload a document — PDF, Word, Markdown, HTML, or plain text — for anything that isn't a product or a CMS page. You get to preview the extracted text before it's added, so you can see exactly what the assistant will learn from it.
4. Website crawl. Point the assistant at a website you own and let it discover and read the pages for you.

What to put where

Content	Best source
Products, prices, stock	Catalogue (automatic)
Policies, FAQ, shipping and returns, About, prose guides	CMS pages/blocks, or upload
A downloadable guide or manual (PDF/Word)	Upload
Prose articles or documentation on a site you own	Crawl
Structured facts — pricing tables, plan or tier comparisons, spec sheets, size charts	A short curated upload (see below)

Getting the most from your catalogue

The assistant reads your products automatically — but how well shoppers can narrow depends on how your attributes are set up in Magento. Colour and size are just two examples; the same machinery works for any attribute you sell on.

• Mark the attributes shoppers narrow by as Filterable / Searchable. Under Stores → Attributes → Product, an attribute set to Filterable (in layered navigation), Filterable in search, Searchable, or Used for sorting becomes something the assistant can filter and sort on — exactly as it already does for colour and size. So a clothing store gets material and style, an electronics store gets connector or capacity, a hardware store gets strength or finish — "cotton shirts", "USB-C cables", "matte black" all narrow, with no extra work beyond the attribute flags you'd set for layered navigation anyway.
• Give numeric attributes a unit in their label. For attributes a shopper quotes with a unit — RAM, weight, power — put the unit in the attribute's label in parentheses, e.g. "RAM (GB)" or "Weight (kg)". That lets the assistant read ranges like "at least 16 GB" or "under 2 kg". Without a unit in the label it can't tell "16" apart from any other number, so it won't range-filter that attribute.
• Product codes enable exact lookups. A shopper who types a SKU always gets that exact product. If you sell books or parts, storing the ISBN, UPC, EAN or MPN as product attributes lets shoppers look an item up by its code too.
• List compatibility for parts (fitment). If you sell parts that fit specific vehicles or models, put the compatible list in a multi-value attribute (e.g. "Fits vehicles": Honda Civic 2015, Honda Civic 2016, …). Shoppers can then ask "brake pads for my 2015 Honda Civic" or "a filter for 2015–2018 Civics" and get only parts that actually fit.
• Reindex after changing attribute settings. When you make an attribute filterable (or add identifier/fitment attributes), run a reindex — or let the automatic schedule do it — so the assistant picks up the change. A reindex is safe to run any time; shoppers keep getting answers while it runs.

What crawling is good for — and what it isn't

Crawling shines with prose pages you own: articles, guides, documentation, and policy pages. It fetches each page, pulls out the readable text, and indexes it. For long-form writing that's spread across a website, it's the fastest way to get everything in.

Crawling is not reliable for structured or laid-out content — pricing tables, plan-comparison cards, spec sheets, size charts. Laid-out content tends to get broken into separate pieces that don't come back together when the assistant searches, so it might surface one row of a table but not reliably list all of them or compare them. For structured facts, don't crawl the page — write a short curated document instead (the next section shows how).

Two more rules for crawling:

• Only crawl sites you own, or have permission to crawl. You confirm this before every crawl.
• Don't index the same thing twice. If you crawl your own store's site, turn off CMS auto-indexing first — otherwise the same pages get indexed twice (once as a CMS page, once as a crawled URL). That adds noise and can let an older copy win in search.

Re-crawling is safe. Different spellings of the same page's address — with or without a trailing slash, with tracking parameters such as utm_source, or with a #section — are treated as one page (extension version 1.2.10 or later). When a page has changed, the new text replaces the old, and an unchanged page is skipped without using any of your allowance.

Curated documents for structured facts (the important one)

For anything the assistant must state completely and exactly — your plans or tiers, a price list, a size chart, a feature comparison — write a short, self-contained document and upload it. This is the difference between "the assistant knows roughly what we offer" and "the assistant lists every plan with the right price and recommends the best fit."

A few simple habits make these documents work:

• One topic per document, kept short. Keep a structured reference to a page or so — roughly 1,500 characters. Short references stay in one retrievable piece, so the assistant always gets the whole thing at once. Longer content gets split up, and the pieces may not come back together — the very problem crawling has with tables.
• List the key facts plainly — one item per line, with the exact figures.
• Add a one-line "which one for whom" if you'd like the assistant to recommend, not just list.

Here's a plans reference — a single uploaded document titled "Our plans":

# Our plans
We offer three plans. All include [shared features]. 30-day money-back guarantee.
- Starter — €X/month. [key specs]. Best for small or new stores.
- Growth  — €Y/month. [key specs]. Best for growing stores with moderate traffic.
- Pro     — €Z/month. [key specs]. Best for high-traffic stores and large catalogues.
Choosing by size: Starter for light traffic, Growth for moderate, Pro for heavy.
You can change plans at any time.

With that one document in place, the assistant can list every plan with the correct prices and recommend one for a shopper's described needs — reliably, because it all arrives together. It reproduces your figures exactly; it won't invent or garble them.

Keeping your knowledge clean

• The document list is your source of truth — everything the assistant has indexed shows up there. Remove items individually (tick the checkboxes and choose Delete selected), or wipe everything with Clear knowledge base. Clearing only affects the assistant's own knowledge — it never touches anything else in your store.
• Recent crawls is just a history of crawl jobs. Prune it with its own Delete selected; doing so doesn't change what's indexed.
• Set priority to give a source more weight. If a shopper's question matches a curated reference and some scraped pages, raising the reference's priority to High or Highest makes it win its own topic — so your carefully written plans document beats stray fragments, without hijacking unrelated questions. From version 1.2.12, a raised priority only applies where the assistant also finds the content relevant by meaning, so a prioritised page that merely shares a few common words with a question doesn't push out better answers.
• After you add or remove content, a reindex (or the automatic schedule, which runs when Magento cron is enabled) refreshes what the assistant knows.

After moving or copying your store

The assistant's searchable knowledge lives in your store's search engine, not in its database. So when you move a store to a new server — or copy it into another store by importing its database and code — your documents, crawl settings and priorities arrive with the database, but the search index the assistant answers from does not. Until it's rebuilt, the assistant has nothing to search and can't answer questions about your content.

• It rebuilds by itself once Magento cron runs. The two Sales Assistant indexes are marked "Reindex required" on the new store, and the automatic schedule rebuilds them within a few minutes of cron starting.
• Or rebuild them yourself with bin/magento indexer:reindex myshopcarts_salesassistant_knowledge myshopcarts_salesassistant_catalogue.
• It uses embedding allowance. Rebuilding re-reads your knowledge documents (a few tens of thousands of tokens for a typical set of pages and documents); the catalogue only costs tokens if meaning search for products is switched on.
• Use the new store's own key. If the database came from another store, it carries that store's assistant key and settings — set the new store's own key first, so the rebuild and every chat count against the right subscription.

Checking what the assistant finds for a question

From version 1.2.11 you can see exactly which of your content the assistant finds for a question, and why. Run this from your store's command line (or, on MyShopCarts hosting, from Run a custom command on the Maintenance tab, without bin/magento). Type the question as plain words, without quotes or a question mark:

bin/magento salesassistant:knowledge:search where can i read about backups

It lists the best-matching sections of your content, best first, with the page each one comes from. For each section it shows:

• sent: one of the five sections the assistant actually receives to write its answer. Content that isn't sent can't be used in the answer.
• kw and mean: how well it matched by keywords and by meaning (1 is the best match; - means it wasn't among the matches at all).
• prio: the priority you set (1 Normal, 2 High, 3 Highest). A priority in brackets, like (2), wasn't applied to that section: it matched only by keywords, not by meaning, so it isn't boosted.
• vec: whether the section can be found by meaning, not only by keywords.

Add --limit=20 to see more than ten results. The command only reads; it changes nothing. Use it when the assistant answers from the wrong page: if the page you expected isn't listed, it isn't in your knowledge base (check the document list); if it's listed but not sent, raise its priority or tighten the content that outranks it.

Rule of thumb

Prose → crawl or CMS. Structured facts → one short curated document. Products → the catalogue. If the assistant has to answer "list them all" or "which one is right for me," you're dealing with a structured fact — curate it, don't scrape it.