Theme integration troubleshooting
Integrating ShopGuide with a theme goes smoothly most of the time, but when it doesn't, the cause is usually one of a handful of predictable things. Here's how to work through them.
The chat block isn't showing up
Whether it's missing from the theme editor's Apps category, or just not appearing on live pages, work through this in order:
- Confirm ShopGuide is installed and your subscription or trial is active (ShopGuide admin → Settings/Billing)
- Confirm your theme is Online Store 2.0 — older themes don't support app blocks at all; see Shopify theme editor basics
- Confirm the ShopGuide Chat block is actually added to the page or template you're looking at — a block only renders where it's been placed
- Confirm pause chat storefront-wide isn't turned on (ShopGuide admin → Settings)
- Clear your browser cache and hard-refresh (Ctrl+F5 / Cmd+Shift+R)
If it's genuinely missing from the template, re-add it: Add Section → Apps → ShopGuide Chat. If the block's there but nothing renders, check the browser console for JavaScript errors, and try a different browser or an incognito window to rule out an extension.
Styling problems
Colors not matching your brand, weak contrast, or the bubble overlapping another fixed element on the page (a cart drawer, sticky add-to-cart bar, cookie banner, mobile nav) all trace back to the same few fixes: adjust colors and the style template on the Appearance page (see Chat appearance & branding), try the opposite corner or enable "Store has mobile navigation bar" (see Chat positioning & layout), or reach for Custom CSS with the widget's real selectors for anything the settings don't cover (see Advanced chat styling).
Chat opens but doesn't respond
Check your plan's visitor limit hasn't been hit (ShopGuide admin → Billing), check your own connection, then open the browser console (F12) and look for JavaScript or network errors. Testing in a different browser, and with other storefront apps or ad blockers temporarily disabled, rules out a conflict. Also worth a quick check: the store-wide pause toggle.
A few browser-specific quirks
Ad blockers and privacy extensions occasionally block the chat's script or its network requests — incognito mode with extensions off is the fastest way to rule this out. Safari and Firefox tracking protection can interfere with anything that depends on analytics consent, like proactive messages, which only load once consent is granted — that's expected behavior tied to Shopify's Customer Privacy API, not a bug. And it's worth confirming you're on a reasonably current browser version before escalating anything further.
On mobile specifically
A bubble that's too small to comfortably tap, or one that overlaps a bottom navigation bar, usually just needs a bigger Bubble size setting (Settings → Bubble) or "Store has mobile navigation bar" turned on. Slower response on older or low-end devices is worth testing on a couple of real phones rather than relying only on the theme editor's mobile preview.
Theme compatibility
Online Store 2.0 is required — app blocks don't exist on older theme architectures. Dawn and other current Theme Store themes work out of the box. A heavily customized or legacy theme may need an upgrade before the block can be added at all; see Shopify theme editor basics.
After any theme update, it's worth confirming three things: the block's still attached where you expect, the bubble still appears and opens correctly, and styling still matches — theme updates occasionally reset custom CSS injected elsewhere.
Digging deeper
In the browser console (F12 on Chrome/Firefox, Develop → Show JavaScript Console on Safari), look for errors from ShopGuide's own scripts — secure-chat-core.js, chat-styles.css, ab-test-engine-bundle.js. In the Network tab, filter for requests to your store's /apps/proxy/... or /apps/ai-agent-proxy/... paths; a failed or slow request there usually points to a subscription, rate-limit, or connectivity issue rather than anything theme-related.
If none of this resolves it, reach out to ShopGuide support with your store's .myshopify.com domain, your theme name and whether it's Online Store 2.0, your browser and version, any console error messages or screenshots, and the steps to reproduce it.