Install the AI Shopping Assistant on your storefront
Copy the embed code from the agent's Install Tags tab into your site's main template, before the closing body tag. On Shopify, turn on the Shopping Assistant app embed in your theme editor instead. Shoppers see the AI Shopping Assistant only while the agent is active.
Before you start
Section titled “Before you start”Use this guide when an agent answers well in the Playground and you want shoppers to see it on your storefront. Stores that use the Webscale AI console add the embed code from Install Tags. Stores that use the Webscale AI app in your Shopify admin turn on an app embed in the theme instead.
The AI Shopping Assistant shows on your storefront only while its agent is active. Draft and inactive agents stay hidden, even with the code in place. If your plan has a monthly conversation limit, the AI Shopping Assistant is also hidden once that month’s conversations are used up. The Install tags reference describes every field on the tab.
Add the embed code to your site
Section titled “Add the embed code to your site”Copy the embed code
- Go to Assistant > Agents and check that the agent's Status reads Active. If it doesn't, turn on the switch in the Status column or select Activate in the row menu.
- Open the agent with Edit in the row menu and select the Install Tags tab.
- Under Step 1 on the tab, select Copy. The button reads Copied! once the code is copied.
- Go to Assistant > Agents and check that the agent’s Status reads Active. If it doesn’t, turn on the switch in the Status column or select Activate in the row menu.
- Open the agent with Edit in the row menu and select the Install Tags tab.
- Under Step 1 on the tab, select Copy. The button reads Copied! once the code is copied.
- Paste the code into your website’s main template, before the closing
</body>tag. The template loads on every page, so the AI Shopping Assistant does too. - Publish the template change to your live storefront. Clear your storefront’s page cache if your platform caches pages.
Confirm the code is on your site
Section titled “Confirm the code is on your site”Confirm the code is on your site
- Back on the Install Tags tab, under Step 2, enter the full address of a storefront page in Website URL, such as your home page.
- Select Confirm. The button reads Verifying... while the console loads the page and looks for your agent's code in it.
- Back on the Install Tags tab, under Step 2, enter the full address of a storefront page in Website URL, such as your home page.
- Select Confirm. The button reads Verifying… while the console loads the page and looks for your agent’s code in it.
Turn on the app embed in Shopify
Section titled “Turn on the app embed in Shopify”- In your Shopify admin, open the Webscale AI app and go to its Get Started page.
- In the Setup guide, find the Enable the widget step and select Enable in Theme Editor. Your theme editor opens at the App embeds panel.
- Switch on Shopping Assistant. Inside the app embed, Enable Shopping Assistant is on by default.
- Leave Agent Code (Optional) blank to use the storefront agent selected in the Webscale console.
- Select Save in the theme editor.
- Return to the Get Started page in the app and select Mark as done on the Enable the widget step. The app can’t detect the app embed, so the step stays open until you mark it.
Check that it worked
Section titled “Check that it worked”Open your storefront in a private browser window and go to any page. The AI Shopping Assistant appears on the page. Open it and check that it shows your agent’s name, logo and welcome message. Ask a question you tested in the Playground. The reply should match what you saw there.
If Ask for cookie consent is on in the agent’s General tab, the message box reads “Accept cookies to start chatting” until you accept cookies in your site’s cookie banner. A private window starts with no cookies, so accept them first, then ask your question.
If you used the embed code, the Install Tags tab shows “Tag installation verified successfully” and “Verified on” with the date after Confirm finds the code on your page. Confirm also saves the Website URL you entered.
Troubleshooting
Section titled “Troubleshooting”| Problem | Fix |
|---|---|
| The AI Shopping Assistant doesn’t appear | Check that the agent’s Status reads Active on Assistant > Agents. Draft and inactive agents stay hidden on the storefront |
| The AI Shopping Assistant is gone, but the agent still reads Active | Your plan’s monthly conversations may be used up. The console then shows “Your assistant is hidden from shoppers”. The AI Shopping Assistant stays hidden until the limit resets. Select See plans in the message to change your plan |
| A shopper sees “Chat is unavailable right now. Please try again later.” | The monthly conversation limit was reached while the shopper had the chat open. Conversations already under way carry on. New ones get this message until the limit resets |
| The message box reads “Accept cookies to start chatting” or “Allow cookies to start chatting” | Ask for cookie consent is on in the agent’s General tab, and this browser hasn’t accepted your site’s cookies. “Allow cookies” means the shopper declined them. Accept them in your site’s cookie banner. To let shoppers chat without accepting cookies, switch off Ask for cookie consent |
| The code block reads “No snippet available” | Select Save on the agent. The embed code appears after the first save |
| Confirm shows that the agent code was “not found in page HTML” | The page your server returns doesn’t contain the code. Check that the template change is published and clear your page cache. Code added by a tag manager isn’t in that HTML, so it can’t pass this check even when shoppers see the AI Shopping Assistant |
| Confirm shows “Website returned status” and a number | The page didn’t load for the check. Use a page anyone can open. The check loads it from Webscale’s servers, so a page behind a password or a bot check can fail |
| Confirm shows “Failed to fetch website” | Check that Website URL is the full address, starting with https:// |
| Confirm shows “Request timed out while checking website” | The page took longer than 10 seconds to load. Try again, or use a faster page such as your home page |
| Confirm shows “Verification failed. Please check the URL and try again.” | Only admins on the account can run the check. Ask an admin to select Confirm, or try again later |
| The code is in the template but nothing shows | Check that the template change is published to your live storefront. Clear your page cache and reload |
| Nothing shows on Shopify after you switch on the app embed | Check that you selected Save in the theme editor and that Enable Shopping Assistant is on |
| Nothing shows on Shopify when Agent Code (Optional) has a value | Check that the code belongs to an agent that exists and isn’t archived. An unknown or archived code shows nothing. Clear the field to use the storefront agent |
| A saved change doesn’t show on the storefront | Reload the page. The AI Shopping Assistant loads saved settings each time a page loads |
Frequently asked questions
- Why doesn't the AI Shopping Assistant appear after I add the embed code?
- The agent is probably not active. Draft and inactive agents stay hidden on the storefront. Activate the agent on the Assistant > Agents list, then reload your storefront.
- Why did the AI Shopping Assistant disappear while the agent still reads Active?
- Your plan's conversations for the month may be used up. If your plan has a monthly conversation limit, the console shows Your assistant is hidden from shoppers when you reach it. The AI Shopping Assistant stays hidden on your storefront until the limit resets. Select See plans in that message to change your plan.
- Do I need to update the embed code when I change the agent's settings?
- No. The embed code only identifies the agent. The AI Shopping Assistant loads its saved settings each time a page loads, so saved changes appear without touching the code.
- Why does Confirm fail when the AI Shopping Assistant shows on my site?
- Confirm reads the page's HTML as your server returns it. Code that a tag manager adds later in the browser isn't in that HTML, so the check can fail even though shoppers see the AI Shopping Assistant.
- Can I use a different agent on a Shopify preview theme?
- Yes. In the preview theme's editor, open the Shopping Assistant app embed and enter that agent's code in Agent Code (Optional). Leave the field blank to use the storefront agent selected in the Webscale console.