Smart Assistant adds your own AI buttons to website pages: “Find an alternative” under a product, a “Top attributes” block, term explanations. AI answers based on your catalog and the shopper’s page.
When you need this:
- Shoppers ask how models differ — a button opens the chat, AI answers about that product.
- Same info on every product page — a button shows ready text without AI.
- Unclear term in a description — the shopper selects it and gets an explanation.
- Shoppers ask “where is my order” — Shop API fetches the live status from your store.
Where to start: describe the product page, then add a block with a button.
What the assistant can do on pages
- Blocks with buttons — embedded into the page before, after or instead of a chosen element.
- Three button display types — ready-made text under the button, a popup window, or a question to AI in the chat.
- Toolbar for selected text — buttons next to the fragment the shopper selected.
- Product filtering — prices, categories, stock: the assistant won’t recommend what you don’t sell.
- Cart actions — buttons call functions of your website.
- Customer orders — statuses from your store without synchronization.
The chat window, operators and knowledge base are covered in smart chat for your website. It’s one widget, and its settings live in one window, on different tabs.
How to tell the assistant which page it is on
To give relevant answers, the assistant needs to know what the shopper is looking at: a product page, a category list or checkout. That’s what page types are for, and each one describes how to recognize it and what to take from it:
- How to recognize — CSS selectors of characteristic elements, part of the URL, characteristic text on the page;
- Product fields — selectors to read the name, SKU, price, stock, photo and attributes from;
- Page buttons — selectors for “Buy”, “Add to wishlist”, “Add to compare”, “Checkout”;
- Section links — search, brands, promotions, blog, contacts, shipping and payment.
You don’t have to fill in all selectors at once. The useful minimum is product page recognition and the name selector: after that, buttons in blocks already get the product name and can talk “about this product” rather than in general terms.
How to add your own AI buttons to a page
A block is a place on the page where the assistant inserts its content. The block list shows the type, name, description, order and activity, and all placement parameters are set in the block card:
| Parameter | What it sets |
|---|---|
| Page type | where the block appears: on the product page, in a category, at checkout |
| selector | the page element to insert relative to |
| Position | Before, After, At the beginning, At the end or Replace this element |
| Block type | Default, Text or Top attributes |
The “Replace” position removes an element of your website and puts the assistant block in its place. You rarely need it — for example, to replace the standard attribute list with “Top attributes”. A wrong selector with this position will break the page layout, so check the result right after saving.
Block buttons
Inside a block live the buttons — they are the main thing. Each button has:
- Name and Tooltip — what the shopper sees;
- Display type — Under button, Popup window or Chat; it decides whether the button calls AI at all (see below);
- Description — ready-made text shown under the button or in the popup window;
- Task for AI (prompt) — the instruction for AI; the field appears in the form only for the Chat type;
- Activity — you can turn a button off without deleting it.
The prompt supports placeholders, and they are what makes a button meaningful:
| Macro | What is inserted |
|---|---|
{ITEM_NAME} | the product name from the page |
{ITEM_ID} | the product identifier |
{HIGHLIGHTED_TEXT} | the text the shopper selected on the page (or taken by a selector) |
Examples: “How is it different from the previous model?” and “Is it right for me?” use the Chat type with {ITEM_NAME} in the prompt: AI answers about this product, and the shopper follows up in the same chat. “Return policy” uses Under button or Popup window with text in Description: it’s the same for all products.
What happens after a button is clicked
The three display types work in fundamentally different ways, and the difference isn’t only where the text appears:
- Under button — the shopper sees the text from this button’s Description field. There’s no AI request: the text arrives on the page together with the block, and the assistant only fills in
{ITEM_NAME},{ITEM_ID}and{HIGHLIGHTED_TEXT}. - Popup window — the assistant requests the same button from the server and shows its Description in a window. No AI request here either. The macros
{ITEM_NAME},{ITEM_ID}and{HIGHLIGHTED_TEXT}are filled in the same way: the product name and ID from the page, and the selected text. - Chat — the chat window opens, and the button name (plus the text taken by the button selector, if set) is sent as the shopper’s message. AI gets the Task for AI (prompt) text as an instruction, with the product name and ID filled in;
{HIGHLIGHTED_TEXT}in the prompt becomes the whole sent message — button name plus selector text. AI replies in the chat. It’s a regular billed AI reply — see cost.
If a button with the Under button type has an empty Description, clicking it opens an empty reply area: this type doesn’t call AI, so there’s nothing to fill it with. The prompt of a button switched from Chat to Under button or Popup window isn’t used.
Toolbar for selected text
A separate mode: when a shopper selects text on the page, your toolbar appears next to it. Buttons are grouped into tabs, each with its own action: a chat message (an AI prompt with the same {HIGHLIGHTED_TEXT}), a click on a page button by CSS selector, opening a link (normally or in a window), JS code, a system event.
This solves a common problem with long descriptions: a shopper who doesn’t understand a term in the specs gets an explanation on the spot instead of leaving to google it.
Which products and prices the assistant shows
When the assistant shows products — in a reply, in a block or in a selection — it takes them from the Elbuz catalog. Two tabs decide exactly how.
Prices
- Price source field — which catalog field to take the price from;
- Currency code, Currency symbol, left, Currency symbol, right — how to write the amount;
- Show old price, Show RRP, Show sale price — what to display next to it;
- Round prices and Show decimals — how the number looks.
Limits
- Category — a list of category IDs to filter products by;
- filtering rules by catalog fields and attributes — so that the assistant only offers what you deliberately sell;
- in-stock products only — don’t recommend what you don’t have.
Category limits aren’t cosmetic, they protect you from awkward answers. Without them, the assistant may offer a shopper a product from an archived or internal category that you don’t show on the storefront. It has one catalog — the same as your store.
A product was disabled or deleted: what the assistant shows
The assistant finds products for a reply in two ways, and in both it checks each product against the Elbuz catalog before passing it to AI: the product must be enabled and pass the filtering rules by catalog fields and attributes from the Limits tab. A disabled or deleted product disappears from the assistant’s replies immediately.
Keyword search — how AI finds products for a shopper’s request — runs on the smart search index. The assistant takes the product name from the catalog and the description from the index.
- The index only includes products with activity and export turned on that are in an active category with export turned on.
- The assistant reads each found product from the catalog: if it was deleted, disabled or cut off by filtering rules, it doesn’t get into the list for AI, and the next found product takes its place.
Index freshness doesn’t decide whether a shopper sees a disabled product — it decides whether a just-enabled or changed product is found and which description AI gets. A product’s index entry is updated immediately when the product is:
- saved in its card;
- changed in the grid — one product or in bulk for the filtered set, including a category change;
- deleted — the entry is removed when “Catalog search index” is turned on in System settings.
If a full reindex is running or already scheduled (it’s started, for example, by data import, a base catalog update from all price lists and a restore from backup), a product change doesn’t touch the index — the next full reindex updates the entry.
The page product and a product by number — the one whose page the shopper is on, and the one AI requests by ID — are read directly from the Elbuz catalog with the same checks.
- If a product is disabled in Elbuz but its page still opens on your website, the assistant doesn’t describe it: to the assistant, it’s a page without a known product.
- If a product isn’t found by number — it was deleted or disabled — the assistant searches the index for that number as keywords, and the results are checked against the catalog again.
How to connect your website links and cart
The assistant lives on your website, so it needs to know its URLs and be able to click its buttons.
Links — URL templates: product, category, product photo, search, cart, checkout, wishlist, compare, promotions. If products came from an external source, links can be taken from there — by source code and template ID, with the {external_url} macro.
Events — your website’s JS code for actions: add to and remove from the cart, add to and remove from the wishlist, add to and remove from compare. Until the functions are set, the buttons are shown but do nothing.
Product ID extraction
For actions to work, the assistant needs the product ID on your side. You set a CSS selector or regular expression to extract the ID from the page, and a separate switch “Always extract ID from product page” — even if the ID is already known from the catalog.
The second switch is needed when the IDs in Elbuz and on the website have drifted apart — after moving the catalog or changing the . Then the page, not the database, becomes the source of truth.
How to show shoppers their orders
The deepest level of integration. The “Links” tab has a Shop block: the URL of the module on your store’s side and a secret key (HMAC), the same here and in the module.
What you get: the assistant knows who exactly is on the website — the shopper’s sign-in is passed to the chat — and can request their orders live, without synchronization. So the answer to “where is my order” comes from your store at the moment of the question, not from a copy of the data.
AI handles questions about a specific order differently for a shopper signed in to their account on your website and for a guest:
- A signed-in shopper sees an order only if it belongs to them; someone else’s order is “not found” for them, even if that number exists. The “my orders” list is available only to them.
- A guest gets only the status, and only after giving the email used to place the order. The order list isn’t available to guests — AI suggests signing in on the website first.
- Start or end
- Action or result
- Decision: the path depends on the answer
The Shop API key gives access to customer data. It’s set as a pair: here and in the store module. The generate button creates a new key, but you must enter it in the module right away — otherwise the connection breaks and the assistant stops recognizing shoppers.
What is paid and where to see the costs
You’re charged only for AI replies. Page blocks and buttons cost nothing by themselves — what matters is whether a specific action calls AI:
| Shopper action | Is there an AI request |
|---|---|
| block button with the Under button or Popup window type | no — the ready-made Description is shown, not billed |
| block button with the Chat type | yes — an AI reply in the chat |
| selected-text toolbar button that sends the selection to the chat | yes — an AI reply in the chat |
| each further shopper message in the chat | yes — each AI reply separately |
| toolbar button with a link or your JS | no |
The billing unit is tokens. For each AI reply, input and output tokens are counted at the prices of the model selected in the AI Model field. If AI searched for products or articles while replying, all intermediate steps of that search are part of the same reply.
Proactive hints and the context card in the chat (the AI blocks on pages and Context card when opening a chat switches) are also generated by AI, but not on every view. Here’s how it works:
- if hints for this page (URL without ad tags — UTM, gclid, fbclid, etc.) and language are already generated, they’re shown from a saved copy — without an AI request; the copy is kept for 365 days;
- if there’s no copy and the visitor hasn’t written anything in the chat yet, there are no hints — and no request;
- if there’s no copy and the visitor has already written in the chat, AI generates hints once — this generation is billed — and then all visitors of this page get them;
- on pages whose URL looks like search, cart, checkout or payment (contains
/search,/cart,/checkout,/order,/pay, etc., or a search parameter likeq=), hints aren’t generated.
- Start or end
- Action or result
- Decision: the path depends on the answer
Where to see what was spent. Each AI reply is recorded in the account’s cost log. A background billing pass sums up the accumulated records and deducts the total from the balance as one line: Balance → Transaction history tab, Operation and Amount columns. So the history shows the total for the period between passes, not each click.
The assistant service doesn’t check the account balance before replying, so with a zero balance Chat buttons and the chat itself keep replying. Billing deducts the accumulated amount with no lower limit — the balance can go negative.
Scenarios
Shoppers on a product page ask how the model is different and whether it suits them
What to set up. A block with a Page type for the product page, containing a button with the Chat display type and a Task for AI (prompt) field with {ITEM_NAME}.
What you get. On click, the chat opens, the button name is sent on the shopper’s behalf, and AI gets your prompt with the product name and ID from the page filled in. The shopper can follow up in the same chat. Each AI reply is billed.
Every product page needs the same info without AI costs
What to set up. A button with the Under button or Popup window display type, with ready-made text in Description.
What you get. The shopper sees the text from Description. There’s no AI request, so clicks aren’t billed.
What won’t happen. AI doesn’t extend or rewrite this text. The prompt of such a button isn’t used, and with an empty Description an empty area opens under the button.
Shoppers write “where is my order”, and the statuses live in your store
What to set up. On the Links tab, in the Shop API block — the Shop API (module URL on the store’s side) and Shop API Secret (the same key as in the module) fields.
What you get. AI requests the order from your store at the moment of the question. A shopper signed in to their account on the website gets their orders with full details; a guest gets the order status after giving the email used to place it.
What won’t happen. The assistant won’t show someone else’s order: for a signed-in shopper it’s “not found”, and the same for a guest without the right email. Until the URL or key is filled in, there are no requests to the store, and AI can’t answer about orders.
You want question hints on pages, but without paying for each view
What to set up. The AI blocks on pages or Context card when opening a chat switch — one of the two is enough.
What you get. Hints for a page are generated once — when it’s opened by a visitor who has already written in the chat — and for 365 days they’re shown to all visitors of this page and language from the saved copy, with no new AI requests.
What won’t happen. Until the page is opened by a visitor who has already written in the chat, it has no hints. On search, cart, checkout and payment pages there will never be any.
What to do when a block or button doesn’t work
| What you see | Why | What to do |
|---|---|---|
| The block didn’t appear on the page | the selector doesn’t find the element, or the page type didn’t match | check the block selector and the page type recognition rules |
| The block is in the wrong place | the wrong position relative to the element is selected | try “Before” / “After” / “At the beginning” / “At the end” |
| The page layout broke | the “Replace” position removed a needed website element | change the position or narrow the selector |
| The button answers in general terms | the prompt has no macros — AI doesn’t know which product it’s about | add {ITEM_NAME}, and {ITEM_ID} if needed |
| The reply appears somewhere unexpected | a different “Display type” is selected | choose “Under button”, “Popup window” or “Chat” |
| The selected-text toolbar doesn’t show | the toolbar has no active tabs or buttons | add at least one button and turn it on |
| The assistant recommends products from the wrong categories | no category limit is set | set up filtering on the “Limits” tab |
| It recommends what’s out of stock | “in stock only” isn’t turned on | turn it on in the “Limits” tab |
| The price in the reply differs from the website | a different price source field is selected, or the sale price isn’t shown | check the settings on the “Prices” tab |
| An empty area opens under the button | the button has the “Under button” type, and “Description” is empty; this type doesn’t call AI | fill in “Description” or switch the button to “Chat” with a prompt |
| The “Add to cart” button does nothing | your website’s JS code isn’t set | fill in the function on the “Events” tab |
| Actions apply to the wrong product | the product ID is extracted incorrectly | check the ID extraction selector or regular expression |
| The assistant doesn’t recognize the shopper | Shop API isn’t set up, or the keys don’t match | compare the module URL and secret key on both sides |
FAQ
How is the assistant different from the chat?
It’s one widget. The chat is the window for messaging with AI and operators; the assistant is what the same widget does on pages: blocks with buttons, the selected-text toolbar, showing products.
How much does an AI button click cost?
Only AI replies are billed — “Chat” buttons and chat messages, by the tokens of the selected model. “Under button” and “Popup window” cost nothing (cost).
Why fill in page type selectors?
So the assistant understands what the shopper is looking at and takes the name, price, stock and buttons from the page. Without them, buttons talk in general terms, and cart actions don’t know which product to apply to.
Why does the assistant offer the wrong products?
Its catalog is the same as your store’s, and filtering isn’t set up. On the “Limits” tab, set categories, filtering rules and showing in-stock products only (limits).
Why doesn’t the assistant describe a product whose page still opens on the website?
The product is disabled or deleted in Elbuz: to the assistant, it’s a page without a known product (disabled product).
Where it is and who has access
- Menu
- Directories → Categories → “Catalog tools” block → “Widget settings - Smart Assistant” tile
- Tabs
- Links, Prices, Limits, Events, Blocks; the rest are covered in widget settings
- Prepare
- the widget code on your website (the same as for the chat) and CSS selectors of your pages
1
Blocks tab2
Limits tab3
Prices tab4
Type column- Blocks tab — the table of assistant blocks placed on store pages.
- Limits tab — restrictions on how the assistant is used.
- Prices tab — price settings of the assistant.
- Type column — the first column of the blocks table.
Related topics
- For the big picture of the chat — smart website chat: where to start.
- If the widget code isn’t on your website yet — how to install the chat on your website.
- If the assistant doesn’t find the right products — smart search.
- If “Top attributes” shows the wrong properties — attributes.
