> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merchantai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How MerchantAI Works: Six Systems Behind Every Answer

> Understand how MerchantAI's six systems work together to answer questions, capture leads, and route conversations to your team with full context.

MerchantAI is not a single model that answers questions in isolation. It is a coordinated system of six purpose-built layers — Knowledge, Workflows, Voice, Routing, Guardrails, and Analytics — that work together to deliver accurate, on-brand responses, take action where permitted, and hand off gracefully to humans when the situation calls for it. Understanding how these systems interact helps you configure the agent to reflect your business precisely and gives you confidence in what it will and won't do when talking to your visitors.

## The six systems

Each pillar in MerchantAI handles a specific job. Together, they form the full lifecycle of a conversation — from retrieving the right information to deciding whether a human needs to take over.

<Accordion title="Knowledge — the source of every answer">
  The Knowledge system is the foundation. Before the agent can answer anything, it needs to know your business. MerchantAI builds a knowledge base by crawling your website pages, indexing your Shopify catalog (products, variants, collections, policies, and blog posts), and incorporating any files or Q\&A pairs you upload manually.

  Every answer the agent gives is retrieved from this approved content — not generated freely from the model's general training. When a visitor asks a question, the Knowledge system finds the most relevant passages from your indexed sources and passes them to the response layer. If there is no confident match in your approved content, the agent does not guess. It either acknowledges it doesn't have the answer or triggers a handover, depending on your configuration.
</Accordion>

<Accordion title="Workflows — actions beyond answering">
  The Workflows system enables the agent to do more than retrieve information. For Shopify stores, it can support product discovery, surface cart review and checkout links, and look up order status — all where your team has explicitly enabled those actions. Sensitive operations such as refunds, cancellations, and account changes remain gated behind human approval.

  For non-Shopify websites, Workflows powers lead capture: the agent collects visitor name, email, phone, and message in a structured sequence, qualifies the enquiry against your rules, and routes it to your team. Every action taken by the Workflows system is logged so your team has a complete record.
</Accordion>

<Accordion title="Voice — brand consistency in every reply">
  The Voice system controls how the agent sounds. You configure a persona and tone (for example, "warm and direct" or "professional and concise"), write or edit the system prompt in plain English, and set per-topic escalation rules. You can also define forbidden topics — subjects the agent will always decline to discuss — and set fallback phrases for situations where the agent hands over rather than answering.

  Voice configuration applies globally across all conversations. The Preview tool lets you test the agent's replies against your own questions before you go live, so you can refine the tone and verify that guardrails are working as expected.
</Accordion>

<Accordion title="Routing — handovers that keep the thread intact">
  The Routing system manages the transition from AI to human. When a handover is triggered — by low confidence, a forbidden topic, an explicit visitor request, or a sensitive action — the agent does not simply drop the conversation. It passes the full transcript, the visitor's contact details, the source content that was retrieved, and the conversation history to your team.

  Handovers can arrive by email, appear in the dashboard Contacts inbox, or both. Your team can review the context and step into the conversation directly, with the full thread visible inline. No context is lost and the visitor is never left without a clear next step.
</Accordion>

<Accordion title="Guardrails — accuracy over assumption">
  The Guardrails system ensures the agent stays honest. It operates on three mechanisms: retrieval-first answers (the agent only uses content from your approved sources), confidence thresholds (if the agent's confidence in a retrieved answer falls below your set level, it escalates instead of guessing), and topic controls (blocklists that prevent the agent from engaging with subjects you have flagged as out of scope, such as medical advice, legal questions, or competitor mentions).

  Guardrails are configurable per agent and can be adjusted at any time from the dashboard. They are the primary mechanism that prevents hallucination and keeps your brand protected on high-stakes pages.
</Accordion>

<Accordion title="Analytics — surfacing what your visitors need">
  The Analytics system runs continuously in the background, collecting data on every conversation. It clusters questions by topic, flags missed answers (questions the agent couldn't answer confidently), identifies source gaps in your knowledge base, and surfaces conversations that were escalated for human follow-up.

  This feedback loop is how you improve the agent over time. When Analytics flags a repeated missed answer, you add the relevant content to your knowledge base. When it flags a source gap, you upload the missing documentation. The result is an agent that gets more capable the longer it runs on your site.
</Accordion>

## Conversation lifecycle

Here is how a typical visitor interaction flows through all six systems from start to finish.

<Steps>
  <Step title="Visitor asks a question">
    A visitor types a message into the chat widget on your website. The message is received by the agent and passed immediately to the Knowledge and Guardrails systems for processing.
  </Step>

  <Step title="Knowledge retrieves relevant content">
    The Knowledge system searches your indexed sources — website pages, product catalog, uploaded files, Q\&A pairs — for the passages most relevant to the visitor's question. The top results are assembled into a retrieval context and handed to the response layer.
  </Step>

  <Step title="Guardrails check confidence and topic">
    Before a response is composed, the Guardrails system evaluates the retrieval results. It checks whether the matched content meets your confidence threshold and whether the question touches any blocked topics. If confidence is too low or the topic is restricted, Guardrails routes the conversation to the Routing system for handover rather than allowing a speculative answer.
  </Step>

  <Step title="Answer delivered or handover triggered">
    If Guardrails clears the response, the agent composes an answer using the retrieved content and the tone rules set in Voice, then delivers it to the visitor. If Guardrails flags the question, the agent presents a handover card — offering the visitor a way to reach your team by email or contact form — while the Routing system sends the full transcript and contact details to your inbox.
  </Step>

  <Step title="Lead captured and conversation logged">
    If the conversation qualifies as a lead — because the visitor provided contact details, expressed purchase intent, or requested a follow-up — the Workflows system records the lead in your Contacts inbox with the full conversation context attached. Analytics logs the entire interaction, updating topic clusters, missed-answer counts, and conversion metrics in your dashboard.
  </Step>
</Steps>

## Supported platforms

<CardGroup cols={2}>
  <Card title="Shopify" icon="shopping-bag">
    MerchantAI has a native Shopify app available on the Shopify App Store. Install it and the widget appears on your storefront automatically. The agent syncs your product catalog, policies, collections, and pages on install and keeps them up to date via webhooks whenever your store changes. Shopify-aware workflows — product discovery, cart review, checkout links, order lookup — are available where enabled.
  </Card>

  <Card title="Any website (JS widget)" icon="code">
    For non-Shopify websites, MerchantAI provides a drop-in JavaScript widget. Copy the single `<script>` tag from your dashboard and paste it before the closing `</body>` tag on your site. The widget works on any platform — WordPress, Webflow, Squarespace, custom HTML, or any CMS that lets you add a script tag. No rebuild and no framework dependencies are required.
  </Card>
</CardGroup>

For headless storefronts and custom setups that need deeper integration, webhooks and a headless API are available on the Exchange and Enterprise plans. Contact the MerchantAI team for details on API access and custom configuration options.

## Data and privacy

MerchantAI is designed with privacy controls appropriate for business and customer conversations. Your knowledge base content is scoped to your workspace and is not shared across accounts. All data is encrypted in transit and at rest. MerchantAI provides a Data Processing Agreement (DPA) to support your GDPR obligations, and privacy documentation — including the Privacy Policy, Security page, and DPA — is available for review before you go live.

Visitors can end a conversation and request deletion of their contact record in one click from the Contacts inbox. Cookie consent and a clear "end chat" control are built into the widget. For detailed information on data processing locations, retention periods, subprocessors, and transfer mechanisms, refer to the current legal documentation on the MerchantAI website.

<Tip>
  Use the **Preview** tool in your dashboard to ask the agent your own questions before deploying to real visitors. Preview runs against your live knowledge base and guardrails configuration, so it accurately reflects what visitors will experience — including handover triggers and topic blocklist behavior. It is the fastest way to catch gaps before they reach your audience.
</Tip>