Installing the Sales Assistant: what happens on your store

When you add the Sales Assistant to your store, it does two things: it installs like any other Magento extension, and then it learns your catalogue so it can answer shoppers from your own products and content. This page walks through the whole sequence, start to finish, so you know exactly what happens and when — including the indexing step that turns your catalogue into something the assistant can search.

This is the Sales Assistant extension. For the general mechanics of adding and updating any extension, see Installing and managing extensions. Once it's running, Feeding your Assistant explains which content to give it and how.

The sequence at a glance

1. The extension is added to your store — installed, enabled, and compiled.
2. Background index jobs are registered — two of them, for your catalogue and your knowledge content.
3. You turn it on and add your key — this is what activates the assistant.
4. Your catalogue and content are indexed for the first time — the assistant reads them and builds a private search index on your store.
5. The chat widget goes live on your storefront.
6. The index keeps itself current — as your catalogue and content change, only what changed is re-indexed, automatically, on a schedule.

The rest of this page explains each step.

1. The extension is added to your store

This is a standard Magento extension install: the extension's code is placed in your store, the module is enabled, your store recompiles, and the web tier is refreshed so the change takes effect. Nothing about your data changes at this stage, and no shopper-facing behaviour changes yet — the assistant isn't active until you turn it on (step 3). If the install can't complete cleanly, it's rolled back and your store is left as it was.

Installing or upgrading never rebuilds the assistant's catalogue index (version 1.2.6 or later). Every extension install runs Magento's setup:upgrade, and on some stores — for example ones with Magento's sample data — that step reindexes all of the store's indexers. The assistant skips its full catalogue rebuild there: it keeps the index it already has, and product changes keep flowing in as usual. You rebuild it only when you choose to (see How the full index is built). On a very large catalogue the install itself can still take a while, because Magento rebuilds its own indexes during it.

2. Background index jobs are registered

As part of the install, the assistant registers two index jobs — one for your catalogue (products) and one for your knowledge (CMS pages and blocks, uploads, and any sites you crawl). These are ordinary Magento indexers: you'll see them under System → Index Management as Sales Assistant Catalogue and Sales Assistant Knowledge.

The extension sets these up for you. During installation it switches both indexers to Update by Schedule automatically — you don't have to configure anything. This hooks them into Magento's own scheduler (cron): Magento records which products and pages have changed, and re-embeds just those on the next scheduled run. It's deliberate that this is the default — indexing is real work, so instead of re-embedding everything every time you save a single product, the assistant keeps the index current in the background. (You can switch either indexer to Update on Save under Index Management if you prefer, but Update by Schedule is the recommended, lighter setting.)

Keeping the embeddings up to date therefore needs no ongoing action from you — as long as Magento cron is running (below), the schedule the extension set up at install does it. The only separate piece is the website-crawl feature: if you crawl a site you own, the extension runs a small background job every minute to work through large crawls a bit at a time. Catalogue and CMS re-indexing use Magento's standard indexer schedule, not that job.

Magento cron must be running for scheduled indexing — and for the automatic refresh in step 6 — to happen. On a managed store this is already handled for you. If you run Magento yourself, make sure cron is enabled.

3. You turn it on and add your key

The assistant stays dormant until you enable it and give it your subscription key. Under Stores → Configuration → Services → Sales Assistant you:

• set Enable widget to Yes,
• paste your subscription's secret key, and
• confirm the assistant's connection details (these are provided with your subscription).

Store hosted with us? If you install the extension from your dashboard (the store's Extensions tab → Install extension), this step is done for you: once the install finishes, the assistant is switched on, its connection details are filled in, and a key is issued and saved to your store. If the store already has a working key, it's left as it is. For a store hosted anywhere else, you do this step yourself as described above.

Your key is stored encrypted and never leaves your store's server — the chat widget in a shopper's browser only ever receives a short-lived, single-session token, never the key itself.

The same screen also has optional appearance and voice settings — the assistant's name, its welcome message, its header colour, and how it describes what you sell. None are required to go live; see Customising your assistant when you want to brand it.

4. Your catalogue and content are indexed for the first time

This is the step most people mean when they ask "what does it actually do to my store?" Once the assistant is active, it reads your catalogue and your knowledge content and builds a private search index on your store.

Here's what that means in plain terms:

• It reads each product and page — names, prices, stock, attributes, and the text of your CMS pages and any documents you've given it.
• It turns them into a searchable form. Your knowledge content — pages, blocks, documents and crawled sites — is converted into a compact mathematical representation, often called an embedding, that lets the assistant match a loosely worded question to the right passage by meaning, not only spelling (what an embedding is). Your products are indexed for keyword search by default (names, descriptions, attributes, prices); you can switch on meaning search for products too — see How it finds products. Either way the assistant first turns the shopper's question into search terms and filters, so it doesn't depend on the shopper typing your exact product names.
• The index lives on your store. Searching your catalogue happens on your own store, against your own index. Your full catalogue isn't copied to us or kept by us — the text is processed to build the index and the index stays with you.

This first index runs automatically after you activate the assistant, in the background. It is deliberately paced so your store doesn't suffer while it runs — your shoppers' pages, searches and checkouts come first, and the indexing uses only what's left over (see Indexing never slows your store). That's why a large catalogue takes a while; the widget can appear before indexing is completely finished, and answers simply get more complete as the index fills in.

When embeddings are created. An embedding is built for a page or document — and, with meaning search for products switched on, for a product — whenever its content is indexed: once for everything during that first full index, and after that only for the items that change (see step 6). Prices and stock are a deliberate exception — they're indexed as filters so the assistant can narrow by them, but their live values are re-read from Magento at the moment it answers, so the assistant never quotes a stale price even if a product hasn't been re-indexed.

Where your index lives: your store's search engine

The Sales Assistant does not run a separate database of its own. It reuses the same search engine your store already uses for catalogue search — your OpenSearch or Elasticsearch cluster (every Magento 2.4 store has one). This is the key to why your catalogue stays with you: the assistant's index lives in your search engine, right alongside Magento's own catalogue index.

Concretely, during configuration and indexing the extension:

• Reads your existing search settings. It takes the host, port, and credentials straight from Stores → Configuration → Catalog → Catalog Search — the same connection Magento already uses. There's no separate cluster to stand up and nothing extra to point it at; if Magento's catalogue search works, the assistant's does too.
• Creates its own indices, namespaced under yours. It adds two indices to that cluster — one for products, one for knowledge — named under your store's existing index prefix so they sit neatly beside Magento's own. It never modifies Magento's catalogue indices; it only adds its own.
• Adapts to what your cluster supports. When it creates its product index, it first tries to enable vector search (k-NN) — the capability that powers semantic matching (understanding "a warm waterproof jacket for hiking", not just the word "jacket"). If your cluster supports it, you get hybrid keyword + semantic search. If your cluster is older or has vector search turned off, the assistant automatically falls back to keyword-only search — it still works, it just leans on wording rather than meaning. For the best answers, run a cluster with vector (k-NN) search enabled.

Because all of this happens inside the search engine your store already runs, searching your catalogue never leaves your store.

How the full index is built

The first index is a normal Magento reindex, run through the two Sales Assistant indexers — Sales Assistant Catalogue and Sales Assistant Knowledge (you'll see them under System → Index Management). On a fresh install they start out marked invalid, so Magento's scheduled reindex builds them in full on its next runs. To rebuild one later from the admin, select it and choose Invalidate index (Magento's Index Management has no "reindex now" action) — the scheduled reindex then rebuilds it within a few minutes.

From the command line you can check their state and build them straight away:

bin/magento indexer:status | grep -i assistant
bin/magento indexer:reindex myshopcarts_salesassistant_catalogue myshopcarts_salesassistant_knowledge

The reindex prints how many items it processed — a useful sanity check (see the troubleshooting notes at the end if it processes zero).

The build works through your catalogue in batches: it reads a group of products, prepares their text (and, for content that uses meaning search, creates its embeddings), writes that group into your search engine, and moves on to the next. The new index is built alongside the current one and only replaces it once it's complete, so shoppers keep getting answers from the existing index throughout — and an interrupted build never leaves you with a half-empty one.

On a store hosted with us, the Reindex button on the store's Maintenance tab rebuilds Magento's own indexes and deliberately leaves the assistant's alone — rebuild the assistant's with the command above when you want to.

Indexing never slows your store

This is a deliberate design choice: we would rather your index take longer to build than have your shoppers notice it being built. A full build is real work, so it's paced to take only a fraction of your store's resources (version 1.2.3 or later):

• It pauses between batches, so it works at most 25% of the time by default.
• Embeddings are created at a steady, limited rate, never in one big burst.
• Shoppers always come first. Answering a shopper's question is never held up by indexing, and in our tests on a busy store, shoppers' page, search and checkout times were unchanged while a full rebuild ran.

The trade-off is time. With products on keyword search (the default), only your knowledge is embedded, so even a large catalogue is ready fairly quickly. With Meaning search for products switched on, embeddings are created at roughly ten thousand products an hour at most, so a catalogue of hundreds of thousands of products can take a day or more to embed completely. Products are searchable by keyword from the start, and meaning-based matching fills in as it goes.

You can change the pace under Stores → Configuration → Services → Sales Assistant → Indexing performance: raise it to finish a big first index sooner on a quiet store, or set 100 to turn the pauses off. Everyday updates — a few changed products or pages — aren't paced; they're small.

If a build is interrupted

If a full build is stopped part-way — the process is killed, the server restarts or your store is moved — the assistant cleans up by itself within about five minutes (version 1.2.9 or later): it removes the half-built index, makes sure product and page changes are being picked up again, and keeps the previous index serving. Start a new build when it suits you.

How much space it uses in your cluster

With products on keyword search (the default), the assistant's product index is roughly comparable to your existing Magento catalogue search index: it stores the product name, description text and the attributes it filters on — much like what Magento already indexes for search.

If you switch on meaning search for products, each indexed entry also carries a semantic vector of about 6 KB, which makes the index typically somewhat larger. A rough planning figure is then ~10–20 KB per product (a product can produce more than one entry, e.g. separate chunks for its description and its specs):

Catalogue size	Approx. assistant product index
5,000 products	~60–125 MB
25,000 products	~250–600 MB
100,000 products	~1–2 GB

Two things that change the figure:

• Without vectors it's much smaller. With products on keyword search, or if your cluster doesn't do vector search, no ~6 KB vectors are stored for products — a fraction of the sizes above.
• The knowledge index is usually small. It's sized by the pages and documents you add, not your whole catalogue, so for most stores it's far smaller than the product index.

The index is stored once (it's created with no extra replica copies), so these figures are the on-disk footprint to budget for in your search engine — on top of what Magento's own catalogue index already uses.

Your plan's allowances: conversations and indexing are separate

Your subscription includes two independent monthly allowances, and it's worth knowing they don't compete with each other:

• A conversation allowance — used when shoppers chat with the assistant.
• An embedding (indexing) allowance — used when the assistant builds or refreshes your index, i.e. when it creates embeddings for your products and content.

They're metered and topped up separately. Indexing draws only on the embedding allowance, so a large re-index never eats into the conversations your shoppers can have, and a busy day of chats never uses up your ability to keep the index fresh.

What uses the embedding allowance, and how much:

• Your knowledge — pages, blocks, documents and crawled sites — is embedded once when it's first indexed, and again only when it changes. For most stores this is a small part of the allowance.
• Your catalogue uses none of it by default. Products are searched by keyword unless you switch on Meaning search for products. If you do, the first pass embeds every product once — roughly, the larger your catalogue and the more text per product, the more it uses, so check your allowance covers it first.
• Everyday edits are tiny — adding or changing a handful of products only re-embeds those items.
• A manual full reindex (System → Index Management → Reindex) re-embeds everything that uses meaning search again, so it costs about the same as the first index. Reach for it when you've made sweeping changes, not for routine edits.

If you exhaust the embedding allowance (extension version 1.2.0 or later):

• Nothing goes missing. Products and pages indexed after that point are still added to your index and found by keyword; only the meaning-based part (the embedding) waits.
• Embedding pauses — the extension stops asking for embeddings instead of failing over and over, and checks once an hour whether your allowance is available again.
• It catches up by itself. When the allowance renews at the start of your next cycle, or grows because you moved to a higher plan, a background job adds the missing embeddings — no reindex needed.
• Your existing index and the live chat keep working throughout, and the conversation allowance is unaffected either way.

You can check where things stand with bin/magento salesassistant:status. It shows:

• whether products use keyword search or keyword + meaning search, and — measured from a sample of your catalogue — roughly how many embedding tokens switching meaning search on would use, against your allowance (--estimate re-measures now);
• how many items are still waiting for an embedding, and whether embedding is paused;
• how much of your embedding allowance is left;
• a full build that's running, stuck or was interrupted (--heal cleans up an interrupted one straight away).

Conversation top-ups add conversations only; the embedding allowance comes with your plan. A large catalogue doesn't need a bigger allowance as long as products stay on keyword search (the default) — only switching on Meaning search for products makes the allowance scale with your catalogue.

5. The chat widget goes live

With the assistant enabled and the first index built, the chat widget appears on your storefront. Shoppers can ask questions and the assistant answers only from your own store's data — your catalogue, your pages, and the documents you've given it. It never invents products or facts, and when a shopper needs a human, it can hand the conversation off to you. When the assistant composes an answer, only the handful of relevant snippets it found in your index, plus the shopper's question, are used to write the reply.

6. The index keeps itself current

You don't have to re-index by hand. Because the index jobs run on a schedule (step 2):

• When you add, edit, or remove a product, that change is picked up and only the affected items are re-indexed — not your whole catalogue.
• When you change CMS pages, upload a document, or crawl a site you own, your knowledge index refreshes the same way. (See Feeding your Assistant for how each source works and how to keep it clean.)
• You can force a full refresh any time: under System → Index Management select the Sales Assistant indexers and choose Invalidate index (the scheduled reindex rebuilds them within a few minutes), run bin/magento indexer:reindex myshopcarts_salesassistant_catalogue myshopcarts_salesassistant_knowledge, or use the assistant's own Knowledge page after adding or removing content.

What leaves your store, and what doesn't

A quick summary, because it's the question that matters most:

• Stays on your store: your catalogue, your content, your search index, and your encrypted key.
• Processed to build the index: your product and page text is sent to be turned into the searchable index, which is then stored on your store. We don't keep a copy of your catalogue.
• Sent when answering a shopper: only the shopper's question and the specific snippets the assistant retrieved from your index — enough to write a grounded answer, and no more.

If something doesn't look right

• The widget doesn't appear: confirm Enable widget is Yes and your key is saved under Stores → Configuration → Services → Sales Assistant, then refresh your store's cache.

• The assistant replies but says it "has no access to the product catalogue": the assistant is connected, but its index is empty — the catalogue hasn't been indexed yet. This is the most common first-run surprise, because on a fresh install the index only builds once Magento cron runs. Build it now:

  • Admin: System → Index Management → tick Sales Assistant Catalogue (and Sales Assistant Knowledge) → Invalidate index → Submit. Magento's scheduled reindex then builds them within a few minutes (cron must be running).
  • Command line: bin/magento indexer:reindex myshopcarts_salesassistant_catalogue myshopcarts_salesassistant_knowledge

  Then reopen the widget and ask again. Two things to check if it still can't see products: the reindex must report more than zero items (zero means your store has no products to index yet), and Magento cron must be running so the index keeps itself up to date afterwards.

• Answers seem thin or out of date: check that Magento cron is running, then run bin/magento salesassistant:status — it reports a stuck or interrupted build (and --heal fixes it). Then rebuild the Sales Assistant indexers (Invalidate index under System → Index Management, or bin/magento indexer:reindex myshopcarts_salesassistant_catalogue myshopcarts_salesassistant_knowledge).

• A specific product or page is missing from answers: make sure it's active and in stock (for products) or enabled (for CMS pages), then reindex.