↑↓ selectEnter openEsc close

    1. Elbuz
    2. Website chat

    How to install the chat on your website

    16 min readUpdated

    Live chat takes one line of code: Elbuz builds it, you paste it into your page template on OpenCart, WooCommerce, Shopify, Horoshop or another CMS, and your site gets an online chat with an AI consultant. You then edit its look in the admin panel.

    When you need this:

    • No chat on your site yet — four steps from the tile to the button.
    • Smart search is already installed — one code loads both widgets, no second line needed.
    • Code pasted, but no button — browser console lines show which check stopped the widget.

    Where to start: step 1 — the “Widget settings - Smart Assistant” tile in “Categories”.

    What installing gives you

    Step 1. Open the settings and check “Activity”

    Open the tile. If the window opens for the first time, the program creates the widget right then, and its “Activity” switch is already on. There's one widget per account: opening the tile again shows the same widget and doesn't create a new one.

    On the “Setup” tab, look at the row of switches at the top. Two of them matter for installation:

    • “Activity” — a disabled widget isn't included in the site code at all, and if the code is already on your site, the chat stops appearing.
    • “Show AI chat” — when off, it removes the chat button from your pages, although the widget itself still loads on the site. It's on by default.

    The window has no “Save” button, and you don't need one. Any field change saves the whole form right away, and the form is saved once more when you close the window.

    Setup tab of the Smart Assistant widget window with the switches row
    1Activity
    2Show AI chat
    1. Activity — a disabled widget disappears from the site code and from the site itself.
    2. Show AI chat — when off, the chat button is hidden, but the widget still loads.

    Step 2. Copy the code

    On the same “Setup” tab, scroll down to the “Integration code” section. The “For widget” field holds the ready code. The field is read-only. The button next to the field name (tooltip “Copy”) copies the whole code, and then the message “Text copied to clipboard” appears.

    Integration code section with the For widget field
    1Copy button
    2For widget field
    1. Copy button — copies the whole code, no manual selection needed.
    2. For widget field — paste this line into the site template once, before the closing body tag.

    What to know about this code:

    • It doesn't contain your settings. Only the service address, the account ID and the widget number. The site gets the button color, texts and AI model again on every page load, so you don't need to change the code on your site after changing the settings.
    • One code for two widgets. If “Smart search” is on as well, the same line loads both. The smart search settings show exactly this code. Your site should have one such line, not two.
    • The field updates only when the window opens. If you turned on “Activity” in a window that was already open, the field still has the old code without the chat. Close the window, open it again, and then copy.

    You can check by eye that the copied code includes the chat: it must contain the address widget-esa.elbuz.com. If it has only widget-ess.elbuz.com, that's the code for smart search alone.

    Step 3. Paste the code into your site template

    The code is a regular <script> block. There's no special module for it: any site whose template accepts your own HTML code will do.

    1. Open the shared template that's output on every page: usually the site footer. An Elbuz CMS store needs nothing pasted: the chat turns on by itself when the store is created (what turns on by itself).
    2. Paste the code before the closing </body> tag. If your CMS has a separate field for third-party scripts in the footer or header, you can use that.
    3. Save the template.

    In OpenCart 3, the shared footer is the file catalog/view/theme/<your theme>/template/common/footer.twig.

    The chat appears only on pages where the code loaded. If you pasted it into the product page template instead of the shared one, there's no chat on the home page or in the cart. Sometimes that's exactly what you want (see typical situations).

    If you paste the code twice by accident, you won't get a second chat: the widget starts only once per page. Still, remove the extra line so you don't have to figure out later which one is the real one.

    Step 4. Check that the chat works

    1. Open your site in a regular browser, not in a speed testing service.
    2. Move the mouse, scroll the page or click anything. The chat button appears only after the visitor's first action (more on this below).
    3. Find the button. With default settings, it's in the bottom left corner.
    4. Open the chat and send a test message. The conversation appears in the “Chat dialogs” window (Organizer → Chat dialogs) as a regular ticket. The article about the “Chat dialogs” window explains how to work with it.

    A test message is a real ticket, and the bot's reply to it is the same AI model call as for any visitor.

    The browser remembers the conversation: if you open the site tomorrow in the same browser, the same chat continues. For a clean check, open the site in a private window.

    If there's no button, open the browser console (F12, Console tab) and find the widget's lines:

    Line in the consoleWhat it means
    Smart Assistant: Initializing widget...The checks passed, and the widget is requesting its settings
    Elbuz widget meta not loaded!The browser didn't load the widget's service file: an ad blocker, the site's security policy or the network
    Smart Assistant: Bot detected or timeout, widget not initializedThere was no action on the page for 30 seconds, or the browser looks like a bot
    Shopping Assistant: Error loading configurationThe service didn't return the settings — most often “Activity” is off

    The line Smart Assistant Widget initialized successfully is printed even when the settings didn't load. On its own it confirms nothing — check whether any lines from the table appear above it.

    Why the chat button may be missing

    The widget goes through several checks, and any of them can stop it silently, with no error on the page.

    Each branch on the right is a separate reason why there's no button. The yellow diamonds are in the order the page goes through them.
    No — ad blocker, CSP,networkYesYes — PageSpeed,headless, botNoNoYesNoYesNoYesA page with the codeopenedDid the widget'sservice file load?No chatconsole: Elbuz widget meta notloaded!Does the browserlook like a bot?No chatDid the visitor move the mouse,scroll or click within 30 seconds?No chaton this page viewIs the widget's“Activity” on?No chatconsole: Error loading configurationIs “Show AI chat”on?No chat buttonChat buttonon the page
    • Action or result
    • Decision: the path depends on the answer

    The bot check raises the most questions. To avoid wasting resources on search engine bots and site testing services, the widget waits for the first human action: a mouse move of at least 10 pixels, a click, a scroll, a key press, a screen touch or focus on an input field.

    • No action within 30 seconds — there's no chat on this page view; it appears after a reload and an action.
    • Browsers that identify themselves as bots (PageSpeed, Lighthouse, headless browsers, search engine bots) never see the chat. So a speed test report without the chat is normal.

    How the chat picks the page language

    The widget detects the page language itself, in this order:

    1. the lang attribute of the <html> tag, the part before the hyphen (uk-UA → uk);
    2. the content-language meta tag;
    3. the og:locale meta tag;
    4. the visitor's browser language.

    The last item is the trap. If your template has no lang and no language meta tags, a visitor with an English browser gets the chat in English even on a Ukrainian page. Make sure every language version of your site has the correct lang.

    The program looks up the site's language code among the languages in the “Languages” window (Directories → Languages): by the “Language code” column, by the “Site language code” column, or by the first letters of the code.

    The site code uk maps to the ua language automatically, while ru, en and pl match as they are. Fill in “Site language code” only when your site marks a language differently from the program; enter the part before the hyphen, because that's all the widget passes.

    Languages window with the language code and site language code columns
    1Site language code
    2Language code
    1. Site language code — fill it in when the site marks the language differently from the app.
    2. Language code — the app's own code; a site code such as uk is matched to the ua language automatically.
    The top three diamonds show where the widget gets the language code: the first sign found wins, and the browser language is the last fallback. The bottom diamonds decide whose texts the chat shows: if the language isn't found in the “Languages” window or has no texts, the chat uses the texts of the first language.
    NoNoNoYesYesYesYesNoYesNoThe widget looks forthe page languageDoes the html taghave a lang attribute?Is there acontent-language meta tag?Is there anog:locale meta tag?Visitor'sbrowser languageCode without regionuk-UA → ukCode found in the “Languages”window?“Language code”, “Site languagecode”or start of the code, uk → uaDoes the “Information” tabhave texts in this language?Texts of the first languageTexts of the found language
    • Action or result
    • Decision: the path depends on the answer

    What depends on the detected language:

    • Chat texts — the window title, the lines in the header and footer: an empty field shows the standard text in the visitor's language, while your own text is the same for all languages.
    • System labels of the chat window itself come in the app's eight languages: Ukrainian, Russian, English, Polish, German, French, Spanish and Italian; other languages get English.
    • Product links that the chat gives visitors are built from the “Site address” field on the “Setup” tab and the product's URL.

    Which domains the code works on

    The code works on any site where it's pasted: the service doesn't check the page's domain, and “Site address” on the “Setup” tab doesn't restrict access. What follows from this:

    • Chats from a test copy or a second domain land in the same “Chat dialogs” window, and product links in the chat lead to the “Site address”.
    • To keep the chat off the test site, remove the code from that site's template. The “Activity” switch turns the chat off on all sites at once.

    How to remove the chat from your site temporarily

    What to doWhat happens on the siteHow to bring it back
    Turn off “Activity”No chat from the next page load. You can leave the code on the siteTurn on “Activity”: the chat returns with all its settings
    Turn off “Show AI chat”The widget loads, but there's no chat buttonTurn the switch back on
    Remove the code from the templateNo chat and no smart search, if it was loaded by the same codePaste the code again

    While “Activity” is off, the code copied from the “For widget” field doesn't contain the chat part. Don't paste code copied during this time onto your site — the chat won't appear after you turn it on.

    Scenarios

    First installation

    Open the tile, make sure “Activity” is on, copy the code from the “For widget” field and paste it before </body> in the shared footer. Open the site and move the mouse — the button appears in the bottom left corner. Then set up the look and texts and the sources of AI answers.

    Smart search is already on your site

    The old code loads only search. Open the chat settings, copy the code again and replace the old line with it — don't add a second one next to it. The new code loads both widgets. For search itself, see the article about smart search.

    You don't need the chat all the time

    For example, when nobody is available to reply. Turn off “Activity” and leave the code on the site. When you turn it back on, the chat returns with the same settings, and you don't need to paste anything.

    A store in two languages

    Check lang in the <html> tag on every language version. Fill in “Site address” on the “Setup” tab and the translations in your company details. If your site marks a language with a code that isn't in the “Language code” column, enter it in “Site language code”.

    Chat on specific pages only

    Paste the code only into the templates of those pages, for example the product page. To open the chat with your own buttons on the page instead of the floating button, use the “Hidden” position (button look) and blocks with AI buttons (smart assistant).

    What to do when the chat button is missing

    What you seeWhyWhat to do
    No button, and not a single widget line in the console The code didn't get into this page's template Open the page source (Ctrl+U) and search for widget-esa. If it's not there, paste the code into the shared template (step 3)
    The page source has widget-ess but no widget-esa The code was copied while the chat was off — it has only smart search Turn on “Activity”, reopen the window, copy the code again and replace the old one (step 2)
    “Elbuz widget meta not loaded!” The browser didn't load the file from widget-esa.elbuz.com Turn off your ad blocker for the check. If your site has a security policy (CSP), allow https://widget-esa.elbuz.com and wss://rt-messaging.elbuz.com in it
    “Smart Assistant: Bot detected or timeout, widget not initialized” 30 seconds without any action on the page, or the browser looks like a bot Reload the page and move the mouse right away (why)
    “Shopping Assistant: Error loading configuration” The widget's “Activity” is off Turn on “Activity” (step 1); you don't need to change the code on the site
    No errors in the console, but no button “Show AI chat” is off, or the button position is set to “Hidden” Turn the switch on (step 1) or change the position on the “View” tab
    The chat speaks a different language than the page The template has no lang, so the widget took the visitor's browser language Add lang to the <html> tag of every language version (chat language)
    Product links in the chat lead to a page that doesn't exist “Site address” on the “Setup” tab is empty or wrong Enter the address of the site's language version on that language's tab (chat language)

    FAQ

    Do I need to change the code on my site after changing the chat settings?

    No. The code doesn't contain your settings, only the service address and IDs. The site gets the color, texts and AI model again on every page load.

    My site already has the smart search code. Should I add another one?

    No, replace it. There's one code for both widgets: the one in the “For widget” field loads both search and chat if both are on.

    Can I allow the chat only on my domain?

    No, there's no domain allowlist. The code works on any site you paste it into, and tickets from there arrive in your “Chat dialogs” window. To keep the chat off a particular site, remove the code from its template.

    Why don't PageSpeed and testing services see the chat?

    The widget doesn't start for browsers that identify themselves as bots, and it waits for the first human action on the page. For testing services, this means the chat won't appear. For people, it means the button appears after a mouse move or a scroll.

    Can I put the chat on certain pages only?

    Yes. The chat is only where the code loaded, so paste it into the templates of the pages you need instead of the shared footer.

    Can I have two different chats for two sites?

    There's one widget per account. You can paste the code on both sites, but the look, texts and AI settings will be the same on both.

    Where it is and who has access

    The widget settings have no menu item of their own. You open them with a tile in the “Categories” window.

    Menu
    Directories → Categories → “Catalog tools” block → “Widget settings - Smart Assistant” tile
    Access right
    the “Categories” window: the widget settings tile is only there
    Have ready
    access to your site template, or a person who can paste code into it

    The same block has the “Widget settings - Smart search” tile. That's a different widget, catalog search, but both share one code for the site — more on that in step 2.

    Catalog tools block in the Categories window with the Smart Assistant and Smart search widget tiles
    1Widget settings - Smart Assistant
    2Widget settings - Smart search
    1. Widget settings - Smart Assistant — opens the chat settings and the code for the site.
    2. Widget settings - Smart search — a different widget, but the site code is shared between them.

    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