Documentation
Live chat widget
The chat widget puts a conversation starter on your storefront. Chats land in the same inbox as your email, so a customer who chats today and emails next week is one history, not two.
Adding the widget to a Shopify store
If you installed Squid Support from the Shopify App Store, you do not need to edit any theme code. The app ships a theme app extension, so the widget is added from the theme editor:
- In Shopify admin, go to Online Store → Themes and choose Customise on your live theme.
- Open App embeds in the left panel.
- Turn on chat-widget-embed, then save.
The extension reads which brand the store belongs to from a metafield that is written automatically when you connect the store, so there is nothing to copy or paste. If you turn the embed on before connecting your store in Squid Support, the theme editor shows a short notice telling you to finish connecting — and your live storefront renders nothing at all rather than a broken script tag.
Non-Shopify sites
For any other platform, use the manual snippet instead. In Squid Support, open Settings → Chat Widget, pick the brand, and follow Step 1: Copy the embed code. Paste it before the closing </body> tag of your site template. Step 2 on the same screen verifies that the widget is loading.
Turning chat on and off
The widget is enabled per brand. On Settings → Chat Widget the Enable chat widget toggle is the master switch for that brand.
This is separate from the theme embed, and the two interact in a way worth understanding. If the theme embed is on but chat is disabled in Squid Support, the widget loads and then renders nothing on the storefront — while showing you an inline notice in the theme editor explaining that chat is switched off in your settings. That way a disabled brand never leaks a half-working chat bubble to shoppers.
Appearance
Under Appearance you can set:
- Horizontal Position — which side of the page the chat button sits on.
- Distance from Bottom (px) — how far up from the bottom edge the button appears, useful when you already have a cookie bar or a sticky cart.
- Primary Color — the accent colour of the button and the customer's own messages.
Under Messages you can set the Greeting Message shown when a customer opens the widget, an Offline Message shown outside your business hours, and Quick Replies — suggested prompts a visitor can tap instead of typing.
A live preview sits beside the settings, so you can check colour and copy before saving.
The pre-chat form
You can ask for an email address before a chat starts with Require email address. Turning this on means every chat arrives already tied to a contact, which lets the AI look up that person's orders straight away and lets you follow up by email if the visitor closes the tab. Leaving it off lowers the barrier to starting a conversation. Most stores that sell physical goods are better off requiring it.
Auto-closing abandoned chats
Shoppers wander off mid-conversation, and those chats would otherwise sit open in your queue forever. Under Auto-close inactive chats:
- Close chats when the visitor leaves — chats close automatically once the visitor has left your site and has not come back.
- Grace period (minutes) — how long to wait after they leave before closing. Accepts 1 to 1440 minutes, so anything from a minute to a full day.
- Optionally, create a linked email ticket containing the chat transcript when a chat closes this way — so an unfinished conversation becomes something your team can still pick up, rather than disappearing.
Presence is what makes this work: the widget reports whether the visitor is still on the site, and agents can see that in the conversation.
When AI answers and when a human takes over
By default chats behave like any other channel — the AI drafts or sends according to your settings, and escalates to your team when it should. See The AI agent for how that decision is made.
There is also an AI-only mode for the chat widget, which requires auto-send to be enabled. In AI-only mode the AI handles every widget chat, and you choose what happens at the moment it would normally hand off to a person:
- Live — escalate to the human team as usual. This is the default.
- None — do not escalate. The AI sends a message explaining the limits of what it can help with and continues handling the chat.
- Ticket — create a linked follow-up email ticket. The AI confirms this to the customer and the chat then closes, so the conversation continues by email instead of leaving someone waiting in a chat window.
Use Ticket if you do not staff live chat outside business hours — the customer gets a clear answer about what happens next rather than silence.
What the widget stores in a visitor's browser
The widget keeps a small amount of data on the shopper's device so a conversation survives a page reload. This matters for your cookie and consent notice, so the exact list is:
| Where | Key | What it holds |
|---|---|---|
| Local storage | helpdesk_visitor_info | The details entered in the pre-chat form |
| Local storage | helpdesk_conversation_id | Which conversation this browser is part of |
| Session storage | helpdesk_customer_token | The chat session token |
The session token is deliberately kept in session storage rather than local storage, so it is cleared when the tab closes and is not left sitting where other scripts on your page can reach it. This storage is strictly necessary to provide the chat the visitor started — no advertising or cross-site tracking is involved. Our privacy policy describes it in the same terms, and you are responsible for how the widget is presented within your own consent notice.
Testing it on your storefront
- Confirm the brand's Enable chat widget toggle is on and the theme embed is enabled and saved.
- Open your storefront in a private or incognito window, so you are testing a genuinely new visitor rather than a cached session.
- Start a chat and send a real question — ideally one about an order that exists in your store, so you can see the AI pull live order context.
- Check the conversation appears in your inbox under the Chat filter, and that the reply is what you expect.
If the bubble never appears, work through Troubleshooting — the usual causes are the embed being enabled on a different theme than the live one, or the brand toggle being off. If you are still stuck, email hello@squidsupport.ai with your store domain.