Skip to main content

Chat block & app embed setup

This guide walks you through adding the "ShopGuide Chat" block to your Shopify store using the theme editor.

Before You Start​

Prerequisites​

  • ShopGuide app installed and an active subscription (or trial)
  • Access to your Shopify theme editor

It Doesn't Matter Where You Add It​

The chat block always renders as a fixed-position floating bubble in the bottom-left or bottom-right corner of the viewport — it is not an inline element that flows with page content. That means the section you add it to (footer, homepage, a custom template) has no effect on where the bubble actually appears on screen; what matters is which pages the block is added to, since a block only renders the chat on the page/template it's attached to.

Most stores add the block once to a section that renders on every page (commonly the footer), so the chat appears everywhere. If you want a different launch message or primary color on a specific page, you can additionally add the block to that page's template with "Use custom settings" enabled — see Custom launch messages.

Step-by-Step Setup​

1. Access Theme Editor​

  1. From Shopify admin, go to Online Store > Themes
  2. Find your active theme and click Customize
  3. Choose the page/template where you want the chat to render

2. Add the Block​

  1. Click Add Section in the left sidebar
  2. Open the Apps category
  3. Click ShopGuide Chat
  4. Click Save

If ShopGuide already created an "AI Guide" page for you during onboarding (Store Setup in the ShopGuide admin app), the block may already be embedded there and this manual step isn't needed.

Block Configuration Options​

These settings live on the block itself (theme editor), and only affect the page(s) that block is placed on:

Custom Launch Message​

  • Use custom launch message — replace the automatic launch flow with your own message for this page
  • Custom Launch Message — richtext message; supports merge tags [[product.title]], [[product.vendor]], [[product.type]], [[collection.title]], [[page.title]], [[shop.name]]
  • Button 1–6 Text — up to 6 quick-action buttons, same merge tags supported

Widget Settings​

  • Use custom settings — override the global chat heading and primary color for this page only
  • Chat Heading — page-specific heading text
  • Primary Color — used for user messages and the container border on this page
  • Product Discussed — auto-fills with the current product on product pages; leave blank for general assistance

Product Comparison​

  • Enable Product Comparison — show a comparison table
  • Up to 3 default product handles to pre-populate the comparison

Side Panel​

  • Show Side Panel on Load — automatically show the side panel with default products/buttons when the chat loads
  • Up to 3 default side-panel items, each either a product handle (renders a product card) or plain text (renders a clickable button)

Testing Your Setup​

Basic checks

  1. The floating bubble appears in the preview and on the live page
  2. Clicking it opens the chat
  3. Sending a test message returns an AI response
  4. Colors and heading match what you configured

Cross-device checks

  1. Preview on mobile and desktop in the theme editor
  2. Confirm the bubble doesn't overlap your theme's own sticky elements (mobile nav bar, sticky add-to-cart, cookie banner)

Common Setup Issues​

Chat Block Not Appearing in the Editor​

  • Confirm ShopGuide is installed and your subscription/trial is active
  • Refresh the theme editor
  • Confirm your theme supports app blocks (Online Store 2.0 themes)

Chat Appears But Doesn't Respond​

  • Check your ShopGuide subscription status in the admin app
  • Check the browser console for errors
  • Confirm the storefront isn't paused via the pause chat storefront-wide toggle in Settings

Next Steps​

Start simple: add the block once to a global section like the footer, then layer in page-specific overrides only where you need them.