tidyAgent user guide

1. Install

1. Install tidyAgent from the Shopify App Store, or open it from Shopify Admin → Apps.
2. Approve the Admin API permissions Shopify shows (full list on /install/shopify).
3. Stay in the Admin iframe while tidyAgent connects — your dashboard opens automatically.
4. Complete onboarding and run a knowledge scan so the AI can learn your catalog and pages.

Always reopen from Shopify Admin → Apps → tidyAgent (not a bookmark or new browser tab).

2. Permissions to enable

These must match Partner Dashboard / shopify.app.toml and what merchants approve at install:

• read_products — catalog, prices, images, variants
• read_content — Online Store pages and blogs
• read_legal_policies — refund, privacy, shipping policies
• read_orders / read_customers — order help and privacy obligations
• read_themes, read_script_tags, write_script_tags — install the storefront chat widget
• read_locales — store languages / markets

After changing scopes, run shopify app deploy, then reopen the app from Admin so Shopify can prompt for the new permissions.

3. Configuring the AI assistant

Go to AI Agent in the dashboard sidebar.

• Name, photo, greeting — how the bubble introduces itself on the storefront.
• Colors & position — widget primary color, optional gradient, text colors, bottom-left or bottom-right.
• Personality & focus — friendly / professional / casual, and whether the agent prioritizes support, sales, leads, products, or bookings.
• Specialists (plan-dependent) — extra agents that only see the knowledge scopes you assign.
• Voice — spoken replies when your plan includes voice.

Use the live preview in Agent Studio before publishing style changes.

4. Managing business knowledge

Open Knowledge. tidyAgent builds answers from:

• Shopify Admin APIs — store profile, pages, blogs, products (prices, images, variants), and legal policies when permitted.
• Owner notes — prices, exceptions, or private instructions you type; these sit above API knowledge and are never overwritten by a rescan.

Click Scan (or re-run the scanner) after major catalog or page changes. Domain crawling / scraping of the storefront is not used for Shopify.

5. Setting up WhatsApp support

During onboarding (Your team) or later in Agent / settings for human support:

1. Enter the team member’s WhatsApp number with the correct country code.
2. Save. Visitors who choose WhatsApp open a handoff that continues the request on WhatsApp.
3. You can also capture email when WhatsApp is not chosen (lead form in the widget).

WhatsApp is optional. Without a number, visitors still get AI answers and can leave email for follow-up.

6. Managing conversations

Open Inbox (or Conversations) in the dashboard.

• See live and past visitor threads for this Shopify store only.
• Open a thread to read the full transcript and reply as a human when needed.
• Leads and WhatsApp handoffs appear in the same workspace so nothing is lost between channels.

7. Configuring human handoff

Handoff starts when the visitor asks for a person, or when the AI cannot answer confidently.

• Set the human team member name, role, email, photo, and optional WhatsApp in onboarding or Agent Studio.
• The widget shows a support choice (email / WhatsApp) instead of inventing an answer.
• Watch the Inbox for new handoffs and continue the conversation from there.

8. Updating support rules and behavior

• Owner notes (Knowledge) — highest priority rules, including private notes visitors never see.
• Agent focus & personality (AI Agent) — how the employee spends its time and tone.
• Specialist scopes — limit what each specialist can see (products, policies, etc.).
• Rescan after Shopify content changes so API knowledge stays current.

9. Chat widget (script tag)

On install / open, tidyAgent registers a storefront script tag through Shopify’s ScriptTag API so the chat bubble appears on your Online Store.

• What it does — shows the chat bubble and talks to tidyAgent’s hosted APIs for replies, leads, and handoff.
• Where it runs — on your published Online Store for visitors.
• Why it is required — without it, shoppers have no chat UI on the live store.
• Remote resources — the script loads hosted files from https://agent.tidyflowapp.com/widget.js (and related embed assets). It does not edit your theme Liquid by default.

10. Disconnecting the App and removing its widget

1. In tidyAgent Settings, use Disconnect. While your Shopify token is still valid, tidyAgent removes only its own script tag and leaves unrelated scripts alone.
2. In Shopify Admin → Apps, uninstall tidyAgent so OAuth access is revoked.
3. Hard-refresh the storefront if a cached bubble remains briefly.

After uninstall we delete or anonymize associated workspace data after a reasonable retention period.

11. Troubleshoot

• App Bridge / connect errors — reopen from Admin → Apps, not a bookmark. Confirm the Shopify API key in tidyAgent Admin Settings matches your Partner client ID.
• Store profile / policies scan warning — ensure read_legal_policies is enabled, deploy the app config, reopen tidyAgent to approve, then scan again.
• No bubble on the live store — finish onboarding, confirm the script tag installed, check theme / Online Store is published.
• Thin answers — re-run Knowledge; add owner notes for facts not in products or pages.
• Billing — Shopify stores use Shopify Billing (charges on the Shopify invoice), not card checkout used for Webflow/Wix seats.