RMS Shop Assistant — Store Manager's Manual

Give your customers instant answers. RMS Shop Assistant adds an AI-powered chat widget to your product pages that answers questions about products, shipping, returns, and store policies — all from your existing Shopify data.

Table of Contents

• 1. Getting Started
  • 1.1 Installing the App
  • 1.2 How It Works — Overview
  • 1.3 What the Assistant Knows
• 2. Dashboard
  • 2.1 Plan and Usage
  • 2.2 Conversation Stats
  • 2.3 Recent Conversations
  • 2.4 Escalation Summary
• 3. Getting Started Guide
• 4. Settings
  • 4.1 Assistant Identity
  • 4.2 Behaviour
  • 4.3 Escalation
  • 4.4 Topics
  • 4.5 Installed Apps
  • 4.6 Language
  • 4.7 Widget Appearance (Theme Editor)
• 5. WhatsApp Integration
  • 5.1 Overview
  • 5.2 Prerequisites
  • 5.3 Setup
  • 5.4 Message Template Approval
  • 5.5 Operating Hours
  • 5.6 How Handover Works
  • 5.7 Two-Way Live Chat
  • 5.8 Handover Scenarios
  • 5.9 WhatsApp Notification Limits
  • 5.10 Troubleshooting WhatsApp
• 6. The Chat Widget
  • 6.1 How Customers Use the Widget
  • 6.2 Topic Quick-Buttons
  • 6.3 AI Responses
  • 6.4 Suggested Follow-Ups
  • 6.5 Escalation to Human Support
• 7. Escalations
  • 7.1 Viewing Escalations
  • 7.2 Responding to Escalations
  • 7.3 Email Notifications
• 8. Analytics
  • 8.1 Overview Metrics
  • 8.2 Product Engagement
  • 8.3 Advanced Analytics
• 9. Subscription Plans and Billing
  • 9.1 Plan Comparison
  • 9.2 Free Plan
  • 9.3 Starter Plan
  • 9.4 Growth Plan
  • 9.5 Enterprise Plan
  • 9.6 Annual Billing Discount
  • 9.7 Free Trial
  • 9.8 Upgrading, Downgrading, and Cancelling
  • 9.9 Conversation Limits
• 10. Privacy and Data Handling
• 11. Frequently Asked Questions
• 12. Troubleshooting
• 13. Support

1. Getting Started

1.1 Installing the App

1. Visit the RMS Shop Assistant listing on the Shopify App Store.
2. Click Add app and authorise the requested permissions.
3. The app installs automatically and you are redirected to the Dashboard inside your Shopify admin.

The chat widget is delivered as a theme app extension and appears on your product pages automatically — no code changes are required.

1.2 How It Works — Overview

RMS Shop Assistant works in three simple steps:

1. Install and configure — Install the app and personalise your assistant's name, personality, and welcome message.
2. Customers ask questions — A chat widget appears on your product pages. Customers click it to ask questions about products, shipping, returns, and more.
3. AI provides answers — The assistant uses your actual store data — product descriptions, pricing, stock levels, store policies, and active discounts — to give accurate, helpful answers instantly.

No training or data upload is required. The assistant reads your Shopify data automatically.

1.3 What the Assistant Knows

The assistant draws all its knowledge from your live Shopify data:

Tip: The more detailed your product descriptions and store policies are, the better the assistant's answers will be.

2. Dashboard

The Dashboard is your home screen, providing an at-a-glance overview of your assistant's activity.

2.1 Plan and Usage

A card at the top shows your current plan and how many conversations have been used this month. A progress bar fills as usage increases, turning red when you approach your plan's limit.

2.2 Conversation Stats

Three key metrics are displayed:

2.3 Recent Conversations

The five most recent conversations are listed, showing the product the customer was viewing (or "General inquiry"), a preview of the last message, and the date.

2.4 Escalation Summary

A sidebar shows escalation counts grouped by status: Pending, In Progress, Responded, and Closed. If there are pending escalations, a "Needs attention" badge is displayed.

3. Getting Started Guide

The Getting Started page provides a step-by-step onboarding wizard with a progress tracker:

1. Install the App — Confirms the app is installed and connected to your store.
2. Configure Your Assistant — Personalise the assistant's name, welcome message, and personality in Settings.
3. Add Support Email — Provide a contact email for when the assistant cannot answer a question.
4. Test Your Assistant — Visit a product page on your storefront to see the assistant in action.

Each step is marked as complete once finished. The page also includes tips for success, quick links to Settings, Analytics, Escalations, and Billing, and a "Need Help?" card with links to the documentation and the contact form.

4. Settings

All configuration is done on the Settings page within the app.

4.1 Assistant Identity

Custom personality selection requires a paid plan. Free plan users use the default "Friendly and helpful" personality.

4.2 Behaviour

4.3 Escalation

Escalation is available on Starter, Growth, and Enterprise plans only.

4.4 Topics

You can add or remove topics from either list to control what the assistant will and will not discuss with customers.

4.5 Installed Apps

If you have other Shopify apps installed that customers might find useful (for example, a size chart app or a "back in stock" notifier), you can register them here. For each app, enter:

• App name — The name of the app (e.g., "RMS Size Helper")
• Button label — What the customer sees on the page (e.g., "Size Guide")

When a customer asks a relevant question, the assistant will suggest they use that app and tell them which button to look for.

4.6 Language

Ten languages are supported: English, Spanish, French, German, Portuguese, Japanese, Chinese, Korean, Italian, and Dutch.

On Growth and Enterprise plans, the assistant can automatically detect the customer's browser language and respond in that language. On lower plans, the assistant always responds in the default language.

4.7 Widget Appearance (Theme Editor)

Additional visual settings are configured directly in the Shopify theme editor, not in the app Settings page:

1. Go to Online Store > Themes > Customize.
2. Navigate to a product page template.
3. Select the RMS Shop Assistant block to see its settings.

5. WhatsApp Integration

RMS Shop Assistant can hand live customer conversations over to your team via WhatsApp. When the AI assistant cannot resolve a customer's question, it escalates the conversation and notifies your team on WhatsApp. Your team replies directly from WhatsApp, and the customer sees the responses in the chat widget on your storefront — creating a seamless two-way live chat.

WhatsApp integration is optional. Without it, escalation works via email and the in-app Escalations page.

5.1 Overview

The integration connects three components:

1. The chat widget on your storefront — where the customer types messages.
2. The RMS Shop Assistant app — which relays messages between the widget and WhatsApp.
3. Your WhatsApp Business account — where your team receives and replies to customer messages.

When an escalation is created, the app sends a WhatsApp notification using a pre-approved message template. Once your team replies on WhatsApp, the conversation enters a live two-way relay: customer messages from the widget are forwarded to WhatsApp, and your WhatsApp replies appear in the customer's widget.

5.2 Prerequisites

To use WhatsApp integration, you need:

5.3 Setup

1. In the app, go to Settings > Escalation tab > WhatsApp Integration.
2. Toggle WhatsApp on.
3. Enter your WABA Phone Number ID, Access Token, Notification Phone Number, and Customer-Facing WhatsApp Number.
4. Click Save.
5. When you save credentials for the first time, the app automatically submits an escalation message template to Meta for approval.
6. Check the Template status badge — it must show "approved" before notifications can be sent.
7. Click Send Test Message to verify that a WhatsApp message arrives on your notification number.

5.4 Message Template Approval

WhatsApp requires all business-initiated messages to use pre-approved templates. When you first save your WhatsApp credentials, the app submits a utility template called escalation_notification to Meta. This template includes:

• The shop name
• The escalation category
• The product the customer was viewing
• The customer's question

Meta typically reviews templates within a few minutes to a few hours. The template status is displayed as a badge in the WhatsApp settings section:

If the template is rejected, review Meta's messaging policy guidelines and resubmit using the Submit Template button in Settings.

5.5 Operating Hours

You can configure operating hours to control when WhatsApp notifications are sent:

1. In Settings > Escalation tab > Operating Hours, toggle operating hours on.
2. Select your timezone.
3. For each day of the week, check the box to mark the day as open and set the start and end times.

During operating hours: WhatsApp notifications are sent normally.

Outside operating hours: WhatsApp notifications are skipped. Email notifications are still sent (if configured), and the escalation is saved in the Escalations page for your team to handle later.

When operating hours are disabled: WhatsApp notifications are sent at all times (24/7).

5.6 How Handover Works

The complete handover flow:

1. Customer escalates — After the AI can't resolve a question (or the escalation threshold is reached), the customer submits an escalation form with their question, category, and optionally their email.
2. App creates the escalation — The escalation is saved in the database and the conversation status changes to "ESCALATED".
3. App sends notifications — Depending on configuration, the app sends a WhatsApp message, an email, or both.
4. Merchant replies on WhatsApp — The merchant's reply is captured via webhook and delivered to the customer's chat widget in real time.
5. Two-way relay begins — The customer can continue typing in the widget. Each message is relayed to the merchant's WhatsApp. Each WhatsApp reply from the merchant appears in the widget.
6. Merchant ends the session — The merchant types /close on WhatsApp to end the live chat. The customer sees "The agent has ended this conversation." and the AI assistant becomes active again.

5.7 Two-Way Live Chat

Once the merchant replies to a WhatsApp escalation notification, the conversation enters two-way relay mode:

From the customer's perspective:

• The chat widget shows a notification that an agent has joined.
• The customer types messages as normal in the widget.
• Agent replies appear in a distinct style (labelled as the agent).
• If the customer leaves and returns, the session resumes automatically if still active.

From the merchant's perspective:

• Customer messages arrive on WhatsApp prefixed with [Customer].
• The merchant replies with plain text — no prefix needed.
• The merchant types /close to end the session and return the customer to the AI assistant.

Session expiry: WhatsApp enforces a 24-hour messaging window. The window starts when the last customer-initiated message is relayed. If 24 hours pass without a new customer message being relayed, the WhatsApp API will reject further relay messages. The customer is informed the session has expired.

Email backup: When the merchant replies via WhatsApp, the customer also receives the response by email (if they provided an email during escalation). This ensures the customer sees the reply even if they have left the widget.

5.8 Handover Scenarios

Here is a summary of what happens under different configurations:

5.9 WhatsApp Notification Limits

Each plan includes a monthly allowance for WhatsApp escalation notifications:

When the monthly limit is reached:

• WhatsApp notifications stop for the remainder of the billing cycle.
• Email notifications continue as normal.
• A warning banner is displayed in the WhatsApp settings section when fewer than 20 notifications remain.
• Upgrade your plan to increase the limit immediately.

5.10 Troubleshooting WhatsApp

WhatsApp test message not received

1. Verify the Phone Number ID and Access Token are correct.
2. Ensure the Access Token is a permanent System User token, not a temporary developer token.
3. Check that the notification number is in E.164 format (e.g. +447700900000).
4. In Meta Business Manager, confirm the phone number is registered and active.

Template status stuck on "pending"

1. Meta template reviews can take up to 24 hours in some cases. Wait and check again.
2. If still pending after 24 hours, try clicking Submit Template to resubmit.
3. Check Meta Business Manager for any account-level issues.

Template rejected

1. Review Meta's messaging policy — templates must not contain promotional content if categorised as "utility".
2. Click Submit Template in Settings to resubmit after making any necessary account changes.

Customer messages not reaching WhatsApp

1. Ensure the escalation status is "IN_PROGRESS" — relay only works after the merchant has replied at least once.
2. Check that the 24-hour WhatsApp messaging window has not expired.
3. Verify webhook configuration in Meta Business Manager — the webhook URL should point to your app's WhatsApp webhook endpoint.

Merchant WhatsApp replies not appearing in widget

1. Confirm the webhook signature verification is working — the META_APP_SECRET environment variable must match your Meta app's secret.
2. Ensure the WHATSAPP_VERIFY_TOKEN environment variable is set and matches the token used during webhook registration.
3. Check the app logs for "Invalid WhatsApp webhook signature" errors.
4. The merchant must reply to (quote) the original notification message or a relayed customer message for the app to correlate the reply to the correct escalation.

6. The Chat Widget

This is what your customers see on your storefront.

6.1 How Customers Use the Widget

A floating chat button appears in the bottom corner of product pages (and collection pages, if enabled). Customers click it to open the chat panel.

If auto-greet is enabled, the widget automatically opens after the configured delay and displays your welcome message along with topic quick-buttons.

When the widget is closed and an auto-greet message has fired, a small notification badge appears on the chat button to draw attention.

6.2 Topic Quick-Buttons

After the welcome message, customers see a set of quick-select buttons for common topics:

• Product Details — Ask about the current product
• Promotions — Check for current promotions or discounts
• Shipping — Ask about shipping options and delivery
• Returns — Ask about the return policy
• Privacy Policy — Ask about data privacy
• Sizing Help — Ask about sizing and fit

Customers can tap a button to start a conversation on that topic, or simply type their own question.

A Browse topics button is also available after every AI reply, allowing customers to return to the topic list at any time.

6.3 AI Responses

The assistant responds in real time. While the AI is composing a reply, an animated typing indicator is shown.

Responses can include formatted text (bold, italic, bullet points, numbered lists, and headings) as well as clickable links. The assistant may link to specific pages on your store when relevant (for example, linking to your returns policy page).

The assistant is aware of which section of the product page the customer is currently viewing and tailors responses accordingly.

6.4 Suggested Follow-Ups

After each AI reply, two to three suggested follow-up questions appear as clickable chips. Customers can tap a suggestion to continue the conversation or type their own question instead.

6.5 Escalation to Human Support

When the assistant determines it cannot confidently answer a question — or when the conversation reaches the escalation threshold — customers are offered the option to submit their question for human follow-up.

The escalation flow:

1. The assistant asks: "Would you like to submit your question for a human to follow up?"
2. The customer clicks Yes, get human help.
3. A short form appears asking for:
   • Category — Product Information, Shipping, Returns, Pricing, or Other
   • Email address — Pre-filled if the customer is logged in
   • Question — A text field for their question
4. The customer submits the form, and the escalation is created.

Escalation is available on Starter, Growth, and Enterprise plans only. On the free plan, the assistant directs customers to your support email address instead.

7. Escalations

The Escalations page is where you manage questions that customers have escalated to your support team.

7.1 Viewing Escalations

Escalations are listed with the most recent first, 20 per page. You can filter by:

• Status — Pending, In Progress, Responded, or Closed
• Category — Shipping, Returns, Product Information, Pricing, or Other

Each escalation shows the customer's email, the category, the product they were viewing, and a preview of their question.

7.2 Responding to Escalations

Click any escalation to open its detail view, which includes:

• The customer's full question
• The complete conversation history (up to 20 messages), showing both the customer's messages and the assistant's replies
• A response text area

Available actions:

7.3 Email Notifications

When a customer submits an escalation, you receive an email notification (if an escalation notification email is configured in Settings). The email includes the category, product name, the customer's email address, their question, and a link to view the escalation in your dashboard.

When you respond to an escalation, the customer receives an email containing their original question and your response, with a suggestion to return to the store if they have further questions.

8. Analytics

The Analytics page provides insights into how customers interact with the assistant. Data covers the last 30 days.

8.1 Overview Metrics

Four key metrics are displayed:

8.2 Product Engagement

A table showing up to 20 products ranked by engagement:

8.3 Advanced Analytics

Available on Growth and Enterprise plans:

• Popular Topics — A ranked list of the most-clicked topic quick-buttons
• Language Breakdown — Conversations grouped by the customer's language
• Daily Activity Chart — A chart showing message volume per day over the last 30 days

Free and Starter plan users see a notice explaining that advanced analytics are available on the Growth plan and above.

9. Subscription Plans and Billing

9.1 Plan Comparison

9.2 Free Plan

The Free plan is ideal for getting started and evaluating the app. It includes:

• 100 conversations per month — suitable for low-traffic stores.
• AI-powered responses — the assistant answers customer questions using your store data.
• Basic analytics — overview metrics and product engagement.
• Topic quick-buttons — customers can browse common topics.
• "Powered by RMS" branding — a small attribution link is shown at the bottom of the chat widget.

9.3 Starter Plan

The Starter plan adds smarter AI and human escalation for growing stores:

• 500 conversations per month — 5x the free plan's limit.
• Smart model routing — the AI automatically uses more capable models for complex questions, providing higher-quality responses.
• Escalation to human support — customers can submit questions for your team to follow up on.
• Email notifications — receive an email when a customer escalates a question.
• Custom personality — choose between friendly and professional tones.
• No branding — the "Powered by RMS" attribution is removed.
• All Free plan features included.

9.4 Growth Plan

For established stores with higher traffic and multi-language needs:

• 2,500 conversations per month — 5x the Starter plan.
• Multi-language auto-detection — the assistant detects the customer's browser language and responds in that language automatically.
• Collection page widget — show the assistant on collection pages, not just product pages.
• Advanced analytics — daily activity charts, popular topics, and language breakdowns.
• Priority support — faster response times from our team.
• All Starter plan features included.

9.5 Enterprise Plan

For high-volume stores that need maximum capacity:

• 10,000 conversations per month — 4x the Growth plan.
• API access — integrate assistant data with external systems.
• All Growth plan features included.

9.6 Annual Billing Discount

Save approximately 17% by choosing annual billing (pay for 10 months, get 12):

Toggle between Monthly and Annual billing on the Billing page using the billing interval switch.

9.7 Free Trial

Every paid plan includes a 14-day free trial. During the trial:

• You have full access to all features of the selected plan.
• You will not be charged until the trial period ends.
• You can downgrade to the Free plan at any time before the trial ends to avoid charges.

9.8 Upgrading, Downgrading, and Cancelling

To upgrade: Go to the Billing page, select a higher plan, and confirm. You will be redirected to Shopify's charge approval page. Once approved, the new plan takes effect immediately.

To downgrade: Select a lower plan (including Free). Your features adjust to the new plan immediately.

To cancel: Select the Free plan or click Cancel plan. Your subscription is cancelled immediately and you are moved to the free plan. Your settings and conversation history are preserved.

All billing is handled through Shopify's built-in billing system. Charges appear on your regular Shopify invoice — no separate payment method is needed.

9.9 Conversation Limits

Each plan has a monthly conversation limit. A conversation is counted when a customer starts a new chat session. When you reach your limit:

• The chat widget stops responding to new conversations for the remainder of the billing period.
• Existing active conversations are not interrupted.
• A usage warning appears on the Dashboard and Billing page when you reach 90% of your limit.

Upgrading your plan or waiting for the next billing cycle restores access.

10. Privacy and Data Handling

RMS Shop Assistant is designed with privacy in mind.

Data collected from customers:

Customer conversations use anonymous session identifiers — no account or login is required. Customer data is not used for marketing and not shared with third parties.

How the AI works:

Conversation content is sent to Anthropic's Claude AI to generate responses. No customer data is stored by the AI provider beyond what is needed to process each request.

Data retention:

• Conversation data is automatically deleted after 90 days.
• Analytics events are retained for 12 months.
• All shop data is permanently deleted following app uninstallation.

Your rights:

The app complies with GDPR and CCPA requirements. Customers have the right to request access to, correction of, or deletion of their personal data. Shopify's standard data request and redaction webhooks are fully supported.

A full Privacy Policy and Terms of Service are accessible from within the app.

11. Frequently Asked Questions

Q: Does the chat widget appear on all pages?

A: By default, the widget appears on product pages only. On the Growth plan and above, you can also enable it on collection pages. The widget does not appear on other pages (home page, cart, checkout, etc.).

Q: Do I need to train the assistant or upload any data?

A: No. The assistant automatically reads your product information, store policies, and active discounts directly from Shopify. There is no training step or data upload required.

Q: How do I improve the quality of the assistant's answers?

A: The assistant's answers are only as good as your store data. To improve quality:

• Write detailed product descriptions.
• Populate product metafields (sizing, materials, care instructions, etc.) in Shopify.
• Set up your store policies under Shopify Settings > Policies (refund, shipping, privacy, terms of service).
• Add alt-text to your product images.

Q: Can the assistant share discount codes with customers?

A: Yes. The assistant automatically knows about your active discounts and promotional codes. When a customer asks about promotions, the assistant will share applicable codes.

Q: What happens when I reach my monthly conversation limit?

A: The widget stops responding to new conversations for the remainder of the billing period. Existing active conversations are not interrupted. A usage warning appears on your Dashboard when you reach 90% of your limit. Upgrading your plan restores access immediately.

Q: Can the assistant answer in different languages?

A: On the free and Starter plans, the assistant responds in the default language you have configured. On Growth and Enterprise plans, the assistant can automatically detect the customer's browser language and respond in that language. Ten languages are supported.

Q: What is "smart model routing"?

A: On paid plans, the assistant intelligently selects the best AI model for each question. Simple, straightforward questions use a fast model for quick replies, while more complex questions use a more capable model for higher-quality answers. On the free plan, all questions use the fast model.

Q: Does the widget work on mobile?

A: Yes. The chat widget is fully responsive and adapts to mobile screen sizes automatically.

Q: What happens to my data if I uninstall the app?

A: All your data (settings, conversations, analytics, and cached store data) is permanently deleted following uninstallation.

Q: Do I need WhatsApp to use the escalation feature?

A: No. WhatsApp is optional. Without it, escalations work via email notifications and the in-app Escalations page. WhatsApp adds real-time two-way live chat between the customer widget and your phone.

Q: What happens if my WhatsApp message template is not approved?

A: WhatsApp notifications will not be sent until the template is approved by Meta. Email notifications continue as normal. Check the template status in Settings > Escalation tab, and resubmit if needed.

Q: Can I use both email and WhatsApp for escalation notifications?

A: Yes. When both are configured, the app sends notifications through both channels. Email serves as a reliable backup — the customer's question is always captured even if the WhatsApp notification is missed.

Q: What is the 24-hour WhatsApp messaging window?

A: WhatsApp requires businesses to respond within 24 hours of the last customer-initiated message. After 24 hours, the relay session expires. The customer is notified and can escalate again or contact you by email.

Q: How do I end a live WhatsApp chat session?

A: Type /close in your WhatsApp reply to end the session. The customer will see "The agent has ended this conversation." and the AI assistant will resume.

12. Troubleshooting

The chat widget does not appear on my product pages

1. Check that the widget is enabled: go to Online Store > Themes > Customize, navigate to a product page template, and confirm the RMS Shop Assistant block is present and visible.
2. If you recently installed the app, try refreshing the product page or clearing your browser cache.
3. Ensure the "Enable on product pages" setting is turned on in both the app Settings and the theme editor block settings.

The assistant gives incorrect or vague answers

1. Review and improve your product descriptions — the assistant uses them directly.
2. Set up your store policies in Shopify Settings > Policies. The assistant reads these to answer shipping, return, and privacy questions.
3. Populate product metafields with sizing, materials, and care instruction details.

Customers are not seeing escalation options

1. Escalation requires a Starter plan or higher. Verify your current plan on the Billing page.
2. Check the escalation threshold in Settings — the customer must exchange at least this many messages before escalation is offered.

I am not receiving escalation email notifications

1. Check that an escalation notification email is configured in Settings.
2. Check your spam/junk folder.
3. Ensure you are on a paid plan — escalation notifications require the Starter plan or higher.

I changed my plan but the features have not updated

1. Refresh the page.
2. If the Shopify billing approval page did not load, try selecting the plan again.
3. Verify the plan change in your Shopify admin under Settings > Billing.

The widget appears but shows no greeting

1. Check that "Auto-greet visitors" is enabled in Settings.
2. Review the auto-greet delay — the widget waits for this duration before greeting. Try reducing it.
3. Verify that your welcome message is not empty in Settings.

13. Support

Need help? Here is how to reach us:

• Email: info@reedmace.net
• Support: Contact us
• Priority support: Available on Growth and Enterprise plans for faster response times.

We are committed to helping your store provide better customer support. If you have feature requests, questions, or need help with setup, do not hesitate to reach out.

RMS Shop Assistant is developed by RMS. All billing is processed securely through Shopify's built-in billing system.