Help Pilot User Manual

An AI shop assistant that actually knows your store — answering product, policy, and order questions 24/7, in any language, with zero theme edits.

helppilot.xyz

Getting started
Installing & turning on the widget
The Dashboard
Settings
Conversations
Billing & plans
The chat widget (shopper experience)
Voice chat
Order lookup & verification
Frequently asked questions
Troubleshooting

1. Getting started

Help Pilot adds an AI chat assistant to your Shopify storefront. It answers shopper questions about your products, store policies, and general store information using live data pulled directly from your store — no separate knowledge base to maintain.

What it can do

Answer product questions — searches your live catalog and shows clickable product cards.
Recommend related products — suggests "you might also like" items to cross-sell.
Add to cart & checkout — adds items to the shopper's cart and hands off to checkout, right inside the chat.
Offer discount codes — optionally mints a one-time, capped discount code to help close a sale.
Explain your policies — refund, shipping, privacy, and terms pages.
List what you sell — surfaces your collections when shoppers ask.
Look up orders — shares order status and tracking after the shopper verifies their identity.
Speak 40+ languages — the widget and the assistant adapt to the shopper.
Talk hands-free (voice) — natural voice conversations on every plan (a free monthly allowance on Free, unlimited on paid).

How it worksShoppers chat through a widget on your storefront. Help Pilot reads your store data through Shopify's secure API and uses OpenAI to write helpful, accurate replies. Order details are never shown until a shopper proves the order is theirs.

2. Installing & turning on the widget

Getting live takes about a minute and requires no code changes.

Install Help Pilot. Add the app from the Shopify App Store, or enter your store domain (e.g. my-shop.myshopify.com) at helppilot.xyz and click Install. Approve the requested permissions.
Open the app. Help Pilot opens inside your Shopify admin on the Dashboard.
Turn on the theme embed. Open your theme editor and switch on the Help Pilot Chat Widget app embed. From Settings you can click Enable in theme editor to jump straight there.
Customize the basics. Set your welcome message, accent color, and (optionally) the bot voice in Settings.
Test it. Click View storefront and try asking a question.

Two switches must both be ONThe widget only appears when both theEnabled on storefronttoggle in Settings and theHelp Pilot Chat Widgetapp embed in your theme editor are turned on.

In Settings → Storefront you'll see one of these banners:

App embed is enabled — Help Pilot is active and shoppers can see the chat widget.
App embed is not enabled — the widget block is turned off; click Enable in theme editor.

3. The Dashboard

The Dashboard is your home screen. It shows your current plan, usage, and a Getting started checklist.

At-a-glance stats

Stat	What it means
Conversations (all time)	Total chats shoppers have started.
User messages (last 7d)	Shopper messages in the past week.
This month's usage	Assistant replies used against your monthly plan quota.
Today's usage	Daily usage (platform-key stores only); resets at 00:00 UTC.

Usage warnings

Help Pilot warns you before you run out:

At 85% of your monthly quota: "You've used X% of this month's messages."
At 100%: "You've hit this month's message limit" with an Upgrade plan button.

When the monthly quota is reached, shoppers see a polite message asking them to try again next month or contact you directly.

4. Settings

Settings → "Customize how Help Pilot looks and behaves on your storefront." Use the Save settings bar to apply changes or Discard to revert.

Widget appearance

Setting	Description
Enabled on storefront	Master switch for the widget. The theme app embed must also be on.
Language	Language for the widget interface and assistant replies (English, Español, Français, Deutsch, Italiano, Português, Nederlands, 日本語, 中文, and more).
Chat title	Header title, e.g. "Store assistant" (max 60 characters).
Subtitle	Small line under the title, e.g. "Your AI Assistant", "Here to help", "Online now".
Avatar image	Optional bot avatar. Drop a PNG / JPG / WEBP (max 2 MB).
Welcome message	The first message shoppers see when they open the chat.
Accent color	Brand color for the widget (hex or color picker).
Bubble position	Bottom right or bottom left.
Launcher icon	Chat bubble, Question mark, Help (life ring), Support headset, or Sparkles (AI).

The Preview sidebar shows a live mock of how the widget will appear.

Capabilities

Choose which topics the assistant is allowed to handle. Turning one off redirects those questions to your support contact.

Products — search the catalog and recommend items.
Collections — list store categories.
Orders — look up order status after verification.
Policies — summarize refund/shipping/privacy/terms.
Add to cart & checkout — let the assistant add items to the shopper's cart and show a checkout button. (On by default; works alongside Products.)
Product recommendations — let the assistant suggest related items ("you might also like").

Discounts

Let the assistant offer a one-time discount code to nudge a sale (for example, when a shopper hesitates on price). This is off by default.

Let the assistant offer discount codes — turns the feature on.
Maximum discount (%) — the largest percentage the assistant may ever offer. Every code is clamped to this on the server, so the bot can't be talked into a bigger discount.

Codes are single-use, expire within about an hour, and are limited to one per conversation. Enabling this asks you to re-approve Help Pilot's permissions (it needs to create discounts).

Product details (metafields)

Give the assistant access to specific product metafields so it can answer detailed questions (materials, dimensions, care, sizing). Off by default.

Let the assistant read product metafields — turns the feature on.
Allowed metafields — a comma-separated list of namespace.key pairs (e.g. specs.material, specs.dimensions). Only the fields you list are ever exposed; everything else stays private.

Customer support contact

Support email

The email the bot shares when it can't help or when a shopper asks for a human. Recommended — without it, the bot has no address to offer.

Voice chat

Available on Starter and Pro (with a 7-day free trial from the Free plan).

Enable voice chat — turns on hands-free voice on your storefront.
Voice — pick the assistant's voice. Options include Marin and Cedar (natural, recommended), Alloy, Ash, Ballad, Coral, Echo, Sage, Shimmer, and Verse.
Hear it — preview the selected voice before saving.

Tone & guardrails

Extra system instructions	Extra guidance on tone and brand voice, appended to the base prompt (max 2000 characters).
Banned topics	Comma-separated subjects the bot must avoid, e.g. "competitors, medical advice, legal advice".

OpenAI (advanced) — bring your own key

Optionally connect your own OpenAI account.

OpenAI API key	Paste your key (`sk-...`) to run on your own OpenAI billing.
Model	gpt-5.4-mini (default, fast and cheap), gpt-5.5 (most capable), or gpt-5.4-nano (cheapest, fastest).
Remove custom OpenAI key on save	Revert to the Help Pilot platform key.

TipWith your own OpenAI key, message usage isunlimited— no monthly quota and no daily cap, since you pay OpenAI directly.

5. Conversations

Conversations → "Recent shopper transcripts."

Every chat is saved so you can review what shoppers asked and how the assistant responded.

The list

Search by shopper email to find a specific conversation.
Filter with tabs: All, Open, Escalated, Resolved.
A Voice badge marks chats that used voice.

Conversation detail

Open any conversation to see the full thread plus a sidebar:

Section	What you can do
Status	Mark resolved, Reopen, or Flag for follow-up. Badges: Open, Escalated, Resolved.
Shopper	View/edit Email (Save email), plus Locale and IP.
Verified orders	Orders the shopper verified, with Active / Expired badges.
Usage	Messages, prompt/completion tokens, and last activity.

EscalationsWhen a shopper asks for a human (or the bot can't help), the conversation is markedEscalatedso you can follow up. Filter by theEscalatedtab to find these quickly.

6. Billing & plans

Billing → "Pricing plans are managed in the Shopify admin." Click Manage plan in Shopify to change plans.

Plan	Price	Monthly messages	Highlights
Free	$0	50	Product, policy & store-info answers; order lookup; standard customization; 20 voice chats / month.
Starter	$20	1,000	Everything in Free, plus unlimited voice chat, 90-day conversation history, and priority email support. 7-day free trial.
Pro	$50	5,000	Everything in Starter, plus conversation export and custom system prompt. 7-day free trial.

"Messages" counts assistant replies. Plan changes are handled by Shopify's secure checkout, then reflected back in Help Pilot automatically.

Help Pilot brandingThe "Powered by Help Pilot" footer appears on theFreeplan. It is hidden on Starter and Pro.

7. The chat widget (shopper experience)

This is what your customers see on the storefront.

Opening the chat

A floating launcher button sits in the corner you chose.
Tapping it opens the chat panel with your title, subtitle, and welcome message.
Before the first message, shoppers see Try asking suggestion chips such as "What are your best sellers?", "What do you sell?", "What's your return policy?", and "Track my order" (only for capabilities you've enabled).

During a chat

Replies can include rich cards for products, collections, policies, and orders.
Product cards link straight to the product page.
The conversation persists as the shopper browses other pages in the same tab.
On mobile, the panel goes full-screen for easy typing.

8. Voice chat

On every plan, shoppers can talk to your store hands-free. Free stores include 20 voice conversations per month; Starter and Pro are unlimited. Voice conversations are counted separately and do not use up your monthly message allowance.

When the message box is empty, a microphone button appears — tapping it starts voice chat.
A voice overlay shows the assistant's state: Listening…, Thinking…, and Speaking.
Barge-in: shoppers can just start talking to interrupt the assistant.
Controls include Pause, Resume, and Exit voice chat.
Voice still shows product and order cards, and works on mobile.

On by defaultVoice is turned on for new installs — pick yourVoicein Settings (or switch it off there any time). You get 20 voice conversations a month on the Free plan; upgrade toStarterany time for unlimited.

9. Order lookup & verification

Help Pilot protects customer data. Order details are only revealed after the shopper proves the order is theirs.

The shopper asks about an order (e.g. "Where is my order?").
The assistant asks for the email address and order number used at checkout.
If they match, the assistant can share status, tracking, and items for that browser session (about 30 minutes).
If they don't match, the bot gives a generic "no match" message without revealing which field was wrong.

Anti-abuseVerification is rate-limited (5 attempts per 5 minutes per session) to prevent guessing.

10. Frequently asked questions

Do I need to edit my theme code?

No. Help Pilot installs as a Shopify app embed — just toggle it on in the theme editor.

Where do the answers come from?

From your live Shopify data (products, collections, policies, orders). There's no separate knowledge base to maintain.

Is voice on by default?

Yes. New installs have voice turned on so shoppers can use it right away. You can turn it off any time in Settings. It's available on every plan — 20 conversations a month on Free, unlimited on Starter/Pro.

What languages are supported?

The widget and assistant support 40+ languages. Set the default in Settings → Language.

What happens when I hit my message limit?

Shoppers see a polite message asking them to try again next month or contact you directly. Upgrade your plan to raise the limit, or add your own OpenAI key for unlimited usage.

Can I control what the bot talks about?

Yes — use Capabilities toggles and the Banned topics field, and add tone guidance under Extra system instructions.

11. Troubleshooting

Problem	Fix
The widget isn't showing on my store.	Confirm both switches are on: Enabled on storefront (Settings) and the Help Pilot Chat Widget app embed (theme editor). Then refresh your storefront.
The bot won't answer order questions.	Make sure Orders is enabled under Capabilities. Shoppers must also verify with email + order number.
The bot can't share a support email.	Add a Support email in Settings → Customer support contact.
The microphone button disappeared from the widget.	On the Free plan voice is limited to 20 conversations a month; the mic returns when the allowance resets next month. Upgrade to Starter/Pro for unlimited voice.
Chat says the store reached its quota.	You've hit your monthly message limit. Upgrade your plan on the Billing page, or add your own OpenAI key.
The microphone won't work for shoppers.	The shopper's browser must grant microphone permission. Ask them to allow mic access and reload.

Need more help? Contact Help Pilot support · helppilot.xyz

Contents