Chat widget
The chat bubble that lives on your storefront. How to install, configure, and customize.
The Humagician chat widget is the visible chat bubble shoppers see on your store. It runs entirely on Humagician's infrastructure — the only thing that lives on your store is a tiny <script> tag.
Installation
Once you've connected Shopify (see Quickstart), the widget script is auto-injected into every store page. No theme code edits required.
To verify, open your store in incognito — the bubble should appear bottom-right after a moment.
If you don't see it, check:
- Widget enabled — Settings → Widgets → toggle Active
- App embed — Shopify admin → Online Store → Themes → Customize → App embeds → ensure Humagician is on
- Browser blockers — some uBlock rules block all chat widgets
Configuration
Each workspace has at least one widget profile. The profile bundles all the settings that make a single bubble. Most merchants only have one; agencies / multi-storefront merchants make several.
Manage profiles at Settings → Widgets.
Title + greeting
| Setting | Where it shows | Default |
|---|---|---|
| Title | Top of the open widget panel | "Chat with us" |
| Subtitle | Smaller text under the title | (empty) |
| Greeting | First message visitors see | "Hi! How can I help?" |
| AI display name | Sender label on AI messages | Huey |
Greeting supports {store_name} as a placeholder.
Branding
- Accent color — primary button + bubble color. Pick anything; we compute readable text contrast automatically.
- Bubble radius — sharp corners, soft, or full pill
- Position — bottom-right or bottom-left
- Logo — optional, shows in the widget header
Behavior
- Auto-engage — pop the widget open after N seconds on a product page (or any page matching a path pattern)
- Require name — ask for visitor's name before the conversation starts
- Require email — same for email; lets you continue the thread by email if they leave
- Operator name display — show operator first name, full name, or a custom alias (e.g. "Sarah from support")
- Inactivity timeout — auto-close abandoned chats after N minutes
- Offline message — what to show when no operators are online
Quick options
The dropdown above the message input. Pre-populate common questions like "Where's my order?", "What's your return policy?", "I want to start a return". Visitors tap one to skip typing.
Configure in Settings → Widgets → Quick options.
Mobile
The widget is responsive. On phones it expands to a near-fullscreen panel; on tablet it's the same side-bubble as desktop. No separate config needed.
Channels
A workspace can support multiple channels (e.g. Storefront chat, Returns line, Wholesale). Each conversation is tagged with its channel; routing rules can target specific channels.
Manage in Settings → Channels.
Theme + dark mode
The widget detects the visitor's prefers-color-scheme and switches palettes automatically. You can force light or force dark in advanced widget settings.
What gets sent over the wire
The widget calls Humagician's hosted API, never your store's backend directly. From your operator console you can see:
- Visitor's current page + cart contents (when Shopify is connected)
- Geo-IP location (city-level)
- Browser + device summary
You'll never see things like password fields or unsubmitted form data.
Embedding outside Shopify
The widget also works on plain websites (Webflow, Squarespace, custom). Drop this script tag in your <head>:
<script
src="https://api.humagician.com/api/humagician/widget.js?w=YOUR_WIDGET_ID"
defer
></script>Find your widget ID in Settings → Widgets → (widget) → Install.