↑↓ selectEnter openEsc close

    1. Elbuz
    2. Website chat

    Smart Assistant on website pages

    17 min readUpdated

    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

    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:

    ParameterWhat it sets
    Page typewhere the block appears: on the product page, in a category, at checkout
    selectorthe page element to insert relative to
    PositionBefore, After, At the beginning, At the end or Replace this element
    Block typeDefault, 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:

    MacroWhat 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.
    The left branch is a shopper signed in to their account: they see full details, but only of their own orders. The right one is a guest: no email, no answer; with an email, only the status.
    yesyesnononoyesyesnoCustomer asks in the chat about anorder by its numberIs the customer signed into their account on your website?The assistant requests the orderfrom the store moduleDid the store find the order,and does it belong to this customer?AI replies with the full order detailsAI replies that the order was notfoundDid the customer give the emailused to place the order?AI asks for the emailThe assistant asks the store for thestatus by number and emailDid the store find an orderwith this email?AI tells the order status
    • 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 actionIs there an AI request
    block button with the Under button or Popup window typeno — the ready-made Description is shown, not billed
    block button with the Chat typeyes — an AI reply in the chat
    selected-text toolbar button that sends the selection to the chatyes — an AI reply in the chat
    each further shopper message in the chatyes — each AI reply separately
    toolbar button with a link or your JSno

    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 like q=), hints aren’t generated.
    Checks run top to bottom. There’s only one paid step — generation, and it’s reached only by a page without a saved copy, opened by a visitor who has already written in the chat.
    noyesyesnoyesnonoyesnoyesA visitor opened a website pageIs AI blocks on pagesor Context card when opening achat on?No hintsDoes the URL look like search,cart, checkout or payment?Are there saved hintsfor this URL and language?The saved copy is shown without anAI requestHas the visitor already written in thechat?AI generates hints, the request isbilledDid AI return hints?The copy is kept for 365 days andshown to every visitor of this page
    • 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 seeWhyWhat to do
    The block didn’t appear on the pagethe selector doesn’t find the element, or the page type didn’t matchcheck the block selector and the page type recognition rules
    The block is in the wrong placethe wrong position relative to the element is selectedtry “Before” / “After” / “At the beginning” / “At the end”
    The page layout brokethe “Replace” position removed a needed website elementchange the position or narrow the selector
    The button answers in general termsthe prompt has no macros — AI doesn’t know which product it’s aboutadd {ITEM_NAME}, and {ITEM_ID} if needed
    The reply appears somewhere unexpecteda different “Display type” is selectedchoose “Under button”, “Popup window” or “Chat”
    The selected-text toolbar doesn’t showthe toolbar has no active tabs or buttonsadd at least one button and turn it on
    The assistant recommends products from the wrong categoriesno category limit is setset up filtering on the “Limits” tab
    It recommends what’s out of stock“in stock only” isn’t turned onturn it on in the “Limits” tab
    The price in the reply differs from the websitea different price source field is selected, or the sale price isn’t showncheck the settings on the “Prices” tab
    An empty area opens under the buttonthe button has the “Under button” type, and “Description” is empty; this type doesn’t call AIfill in “Description” or switch the button to “Chat” with a prompt
    The “Add to cart” button does nothingyour website’s JS code isn’t setfill in the function on the “Events” tab
    Actions apply to the wrong productthe product ID is extracted incorrectlycheck the ID extraction selector or regular expression
    The assistant doesn’t recognize the shopperShop API isn’t set up, or the keys don’t matchcompare 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
    Smart Assistant widget settings window, Blocks tab with the table of assistant blocks
    1Blocks tab
    2Limits tab
    3Prices tab
    4Type column
    1. Blocks tab — the table of assistant blocks placed on store pages.
    2. Limits tab — restrictions on how the assistant is used.
    3. Prices tab — price settings of the assistant.
    4. Type column — the first column of the blocks table.

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free