Install guides / Shopify
Install the SupportHQ widget on Shopify
Shopify stores add site-wide scripts by editing the theme layout file. It is a small change: two script tags before the closing body tag in theme.liquid. The widget then appears on every storefront page.
An AI agent on a store handles the questions that flood a small merchant's inbox: shipping times, returns, sizing, order status policy. Load your shipping and returns pages into the knowledge base first so it has something to answer from.
Requirements: Works on any Shopify plan that lets you edit theme code (all standard plans). The checkout page is not customizable with theme scripts unless you are on Shopify Plus.
Steps
- 1
Copy your embed code from SupportHQ
In the SupportHQ dashboard open your project, go to Integrations, choose Web chat, and copy the HTML snippet.
- 2
Open the theme code editor
In Shopify admin go to Online Store, Themes. On your current theme click the three dots (or Actions) and choose Edit code.
- 3
Edit theme.liquid
Under Layout open theme.liquid. Scroll to the bottom and paste the snippet just above the closing body tag.
- 4
Save and check the storefront
Click Save. Open your storefront in a private window. The launcher should appear on the home page, product pages, and cart.
Where it goes: Online Store, Themes, Edit code, Layout, theme.liquid, immediately before the closing body tag.
The snippet
Replace YOUR_PROJECT_ID, or copy the ready-made version from Integrations, Web chat in your dashboard.
<script src="https://cdn.supporthq.app/widget/latest/supporthq-widget.js"></script>
<script>
SupportHQWidget.init({
projectId: 'YOUR_PROJECT_ID',
})
</script>Things that go wrong on Shopify
- The edit is per theme. If you switch or duplicate themes, add the snippet again in the new theme.liquid.
- The checkout page does not load theme scripts on standard plans, so the widget will not appear there. This is a Shopify limitation.
- Some theme apps inject their own chat launcher in the same corner. Set position: "bottom-left" in the init options, or remove the other app.
- If your theme uses a preview or "customize" mode, test on the published storefront URL instead.
Verify it works
- Open the published page in a private browser window. The launcher bubble should appear in the bottom-right corner within a second or two of the page loading.
- Click the bubble and ask a question your knowledge base covers. The reply should come from your content. Ask something it does not cover and confirm it says it does not know and offers to bring in a person.
- Open the same page on a phone. The panel should open full-height and the keyboard should not cover the reply.
- Check the SupportHQ inbox. The test conversation should be there with the page URL in its metadata.
FAQ
Can the agent answer order status questions?
It answers from your knowledge base, so it can explain your order status policy, shipping windows, and how to find a tracking link. It does not look up a specific order in Shopify. For a specific order, it hands off to your team with the customer's details.
Does it work on the Dawn theme?
Yes. Dawn and all Online Store 2.0 themes have a theme.liquid layout file. The steps above are the same.
Where do I find my project ID?
In the SupportHQ dashboard, open your project, go to Integrations, and choose Web chat. The embed code shown there already contains your project ID and any options you set (theme color, position, required fields). Copy it from there instead of typing it.
Will the widget slow my site down?
The script loads from a CDN. Place it at the end of the body, or use the async pattern shown for React and Next.js, and it will not block your page from rendering. Your content paints first.
Can I put the widget inside the page instead of a floating bubble?
Yes. Add a container element and pass mode: "embedded" and, if needed, container: "#your-id" to init. The chat renders inside that element at the width and height you set.