WisWes Documentation

Dashboard

The landing page at app.wiswes.com is a single dashboard. The left-hand nav groups configuration, behavior, experiments, channels, observability, and administration.

Tool model

Under Configuration → Model you pick which LLM runs tool calls and classification for the agent. Wes supports two execution modes:

What is embedding

Embedding turns a block of text (a policy, a product description, a past conversation) into a vector — a numeric fingerprint the agent uses to find similar content at query time. In WisWes, embeddings power:

• Retrieval-augmented answers — policies and FAQ docs are embedded; when a shopper asks "what's your return window?" Wes looks up the closest passage in sub-millisecond time before answering.
• Intent matching — each intent you train is embedded. Incoming messages are embedded the same way and matched by cosine similarity.
• Product semantic search — product descriptions are embedded so the agent can find "quiet noise-cancelling headphones for meetings" even if those exact words aren't in your catalog.

Embeddings live in Qdrant. The embedder itself is configurable under Model — default is text-embedding-3-small via OpenAI.

System prompt

The system prompt is where you teach Wes your brand voice, refusal policy, escalation rules, and house style. It's plain English — no YAML, no flow diagrams. Edit, save, and the next conversation uses the new version.

Typical prompt structure

You are Wes, the shopping assistant for {{store.name}}.

## Voice
- Friendly, concise, never pushy
- Address the shopper by first name if available
- Use the shopper's language; if unclear, default to English

## Rules
- Never promise a delivery date you haven't verified via a tool
- Never apply discounts that aren't in the configured promos
- If asked for a human, call handoff:escalate

## Tools
You have access to: product:search, product:get, cart:*, order:*, customer:info.
Prefer product:search for discovery, product:get for exact SKU lookups.

## Shop context
{{store.policies}}

How to connect commerce

Configuration → Commerce is where you wire WisWes to your store. One of:

• Magento 2 — install the wiswes/module-mcp Composer package, click Install from the Magento admin to mint a shared secret, you're live. Full guide at /install/magento.
• Shopify — connect your myshopify.com domain in the WisWes commerce config and paste the embed snippet into theme.liquid. Full guide at /install/shopify.
• Custom MCP server — any stdio or HTTP MCP endpoint. Shopware / BigCommerce adapters ship as custom MCP servers we build on request.
• REST init endpoint — for the widget to know the current shopper's cart and identity, WisWes calls a platform-specific /chat_ai/chat/initialize endpoint on page load. The endpoint returns { customer_id, cart_id, locale, currency }.

Minimal Magento connection

# 1. Install the module
composer require wiswes/module-mcp
bin/magento module:enable WisWes_MCP
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

# 2. From Magento admin: Stores → Configuration → WisWes Chat → Install
#    Magento mints a shared secret and redirects you to the WisWes dashboard,
#    which records the secret on your tenant. No CLI server to run — the MCP
#    endpoint is served by Apache/PHP-FPM at https://<your-magento>/mcp.

# 3. (Optional) push the catalogue to the WisWes vector index immediately
bin/magento wiswes:products:push

Intents — what they are + how to add them

An intent is a named bucket of example phrases that mean the same thing. The first-turn classifier embeds the shopper's message and matches it against your intents. Matched intents can trigger a Flow, change the system prompt variant, or unlock specific tools.

Adding an intent

1. Open Behavior → Intents and click New intent.
2. Name it in snake_case — order_tracking, size_guidance, return_request.
3. Add 6–10 example phrases. Cover formal, casual, typos, and at least one foreign-language version if you sell abroad.
4. (Optional) pick a Flow to trigger when this intent matches with confidence ≥ 0.82.
5. Save. No retrain step — embeddings are recomputed synchronously.

Tools — add via MCP, override, limits

Tools are the agent's actions — anything from product-filter tocrm-loyalty-tier. In WisWes, tools always come from an MCP server: the Magento module we ship, a custom server you write, or any MCP-compliant endpoint.

Adding a tool via MCP

Drop a class into your MCP server and annotate it. Here's a minimal example for the Magento module — a custom loyalty-points lookup:

<?php
declare(strict_types=1);

namespace WisWes\MCP\Mcp\Tool\Loyalty;

use PhpMcp\Server\Attributes\McpTool;

class LoyaltyPointsTool
{
    public function __construct(
        private readonly \Acme\Loyalty\Api\PointsClient $client,
    ) {}

    #[McpTool(
        name: 'loyalty-points',
        description: 'Returns the authenticated customer\'s loyalty tier and current points balance. Arguments: none. Customer access token required.'
    )]
    public function points(): array
    {
        $snapshot = $this->client->snapshotForCurrentUser();
        return [
            'tier'   => $snapshot->getTier(),
            'points' => $snapshot->getBalance(),
            'tier_progress' => $snapshot->getProgressToNext(),
        ];
    }
}

After bin/magento setup:di:compile && bin/magento cache:flush, the tool appears in WisWes under Tools within seconds — the MCP endpoint is served by Apache/PHP-FPM, so a deploy is enough; no separate process to restart.

Overriding an action

You can change what the agent sees without editing PHP. On any tool row, clickOverride — you can:

• Edit the description the model reads (e.g. tighten when to call it, add preconditions).
• Pin argument defaults (force perPage=25 everywhere).
• Whitelist/blacklist fields in the response (strip PII before handing back to the model).
• Wrap in a pre-action hook — call a webhook before the tool fires.

Limits

• Max 64 tools per workspace the model sees in one conversation.
• Max 16 tool calls per conversation turn.
• Tool call timeout: 20 s — raise in Model settings if your MCP is slow.
• Per-tool rate limit configurable (default 60 calls/min/conversation).

Flows — scripted paths the agent drives

A Flow is a graph of steps. Each step has a role (user-facing text, tool call, classification, handoff) and branching rules. Flows are how you express "after the shopper is identified, check loyalty tier and show VIP pricing if eligible"without hand-written prompt engineering in every conversation.

Adding a flow via MCP (example: refund wizard)

You don't write Flows in code — they live in the database (flows +flow_steps). But the tools the Flow calls come from MCP. Example: a refund Flow that uses order:info, order:update, and a newrefund:initiate:

#[McpTool(
    name: 'refund:initiate',
    description: 'Starts a refund for the given order. Arguments: orderId (int), reason (string), amount (float, optional — omit for full refund). Admin token required.'
)]
public function initiate(int $orderId, string $reason, ?float $amount = null): array
{
    $refund = $this->refundService->create($orderId, $reason, $amount);
    return [
        'refund_id' => $refund->getId(),
        'status'    => $refund->getStatus(),
        'amount'    => $refund->getAmount(),
        'eta_days'  => $refund->getEtaDays(),
    ];
}

Overriding a flow step action

The same override panel that works for Tools also works inside a Flow step. You can hard-pin argument defaults (e.g. force notify=true on allorder:update calls in the Refund Flow) without touching MCP source.

Limits

• Max 32 steps per Flow.
• Max 4 nested Flows (a Flow calling a Flow).
• Max 90 s wall-clock per Flow — steps beyond that surrender back to the free-form agent.
• Steps that mutate state (cart, order, customer) must declare side_effect: true — the conversation replay UI will mark them read-only so a CS rep can't accidentally re-fire them.

FAQs — teach the assistant your business answers

FAQs are curated question/answer pairs that capture how your business actually replies to recurring shopper questions: return windows, sizing rules, store hours, warranty policy, the wording of your delivery promise. The assistant retrieves the closest match at query time and uses it as ground truth — so answers stay on-brand and stop drifting into LLM hallucinations.

Adding entries by hand

1. Open Behavior → FAQs (or, on the Basic plan, the standalone FAQs menu).
2. Click New entry.
3. Write the question the way a shopper would phrase it.
4. Write the canonical answer in your brand voice — links and short paragraphs are fine.
5. (Optional) add tags so you can filter the list later, e.g. returns, shipping.
6. Save. Embeddings are recomputed synchronously — the entry is searchable immediately.

Bulk import via CSV

On the FAQs page click Import CSV to load many entries at once. The file is parsed server-side, embedded, and indexed in one shot.

File format

• First row must be the header line: question,answer,tags.
• question and answer are required. tags is optional.
• Tags use a pipe to separate values, e.g. billing|invoices.
• Save the file as UTF-8. Wrap any cell that contains commas, quotes, or newlines in double quotes; escape internal double quotes by doubling them ("").
• One row per Q&A pair. Empty rows are skipped, malformed rows are reported back per-row.

Example

question,answer,tags
What is your return policy?,"Returns are accepted within 30 days of purchase.",returns|policy
How do I track my order?,Use the link in your shipping confirmation email.,shipping
"Do you ship internationally?","Yes, we ship to over 40 countries.",shipping|international

Download faq-sample.csv and edit it in Excel, Numbers, or Google Sheets — just remember to export back as UTF-8 CSV.

Why it matters

• Accuracy: the model quotes your wording instead of inventing one.
• Speed to ship: answer a new policy question in 30 seconds, no deploy.
• Per-tenant scope: each workspace owns its own FAQ index — your answers, your data.
• Always available: FAQs are part of every plan, including Basic.

Products — semantic catalogue search

The product:search tool finds products by meaning, not keyword. A shopper saying "something tart for a kid's birthday" matches a product whose description mentions sour fruit cake, party-friendly even though none of those exact words appear in the query. Embeddings live in a tenant-scoped Qdrant collection, fully isolated from other workspaces.

Two payloads per product

Every entry has two halves that the assistant treats very differently:

• Metadata — free-form text that builds the search embedding. The LLM never sees this directly; it's the "by which the product is found" payload. Pack it with anything a shopper might phrase: descriptions, flavour notes, occasions, materials, configurable option labels, dietary tags, use cases.
• Retrieval — a structured {url, sku, name, min_price}dict returned to the LLM verbatim when the row matches. Keep it minimal: every retrieved product contributes to the LLM's context window, and longer retrieval payloads directly increase your model API spend.

Adding products by hand

1. Open Knowledge → Products (or, on Basic, the standalone Products menu).
2. Click Add product.
3. Fill in the Metadata textarea — anything you want shoppers to be able to find this product by, in any phrasing.
4. Fill in the four retrieval fields: name, sku,url, min_price. These are what the assistant cites in the chat reply.
5. Save. The embedding is recomputed synchronously — the entry is searchable immediately.

Bulk import via CSV

On the Products page click Import CSV to load many entries at once. Up to 20,000 rows per file (the per-tenant plan cap still applies).

File format

• First row must be the header line: metadata,url,sku,name,min_price.
• metadata is required — it's what the embedding is built from. The other four columns are returned verbatim to the LLM when this row matches.
• Save the file as UTF-8. Wrap any cell that contains commas, quotes, or newlines in double quotes; escape internal double quotes by doubling them ("").
• One row per product. Empty rows are skipped, malformed rows are reported back per-row.

Example

metadata,url,sku,name,min_price
"Tart, fruity. Great for kids' birthdays. Vegan option.",https://shop.example.com/sour-apple,SKU-001,Sour Apple Cake,$24.99
"Rich dark chocolate. 70% cacao. Gluten-free.",https://shop.example.com/dark-choc,SKU-002,Dark Chocolate Slab,$12.50

Plan limits

• Basic: up to 100 indexed products.
• Pro: up to 10,000 indexed products.
• Enterprise: unlimited.

Cost considerations

Each chat that retrieves products pays for those products in input tokens. A 50-word retrieval payload across the top 3 matches is ~150 tokens added to every relevant turn. Keep retrieval lean: name + sku + url + price covers most shopping intents without bloating context. If you find yourself wanting to stuff long descriptions into retrieval, push them into metadata instead — the search will still find the product by them, but they won't cost tokens at chat time.

A/B testing

Creating a campaign

1. Experiments → A/B testing → New campaign.
2. Pick what you're varying: system prompt, Flow, tool description, model (e.g. Sonnet vs Haiku), or personalized promo strategy.
3. Define the metric: conversion rate, AOV (avg order value), CSAT, handle time, or a custom event emitted by the widget.
4. Set the traffic split (default 50/50) and optional audience (logged-in only, country, VIP tier).
5. Start. Routing is deterministic by session_id, so the same shopper always sees the same variant.

Validating results

The campaign card shows, for each variant:

• Traffic (sessions assigned) and confidence interval.
• Metric value in real money / real percentage points.
• Relative lift vs control and a Bayesian "probability this variant is best".
• Secondary-metric dashboard (so a prompt change that lifts conversion but tanks CSAT is caught).

Widget configuration

Channels → Widget controls the chat bubble your shoppers see. Colors, position, greeting message, opening hours, proactive triggers, and the one-liner snippet you paste into your theme.

Install the widget

<!-- Paste before </body> -->
<script>
  (function(w,d,s,u){
    w.__wiswesConfig = { tenant: 'YOUR_TENANT_SLUG' };
    var j = d.createElement(s); j.async = true;
    j.src = u + '/widget.js';
    d.getElementsByTagName('head')[0].appendChild(j);
  })(window, document, 'script', 'https://cdn.wiswes.com');
</script>

On Magento 2 the module we ship does this injection for you — enable the widget inStores → Configuration → Services → Chat AI MCP → Widget and you're done.

Conversations UI

Observability → Conversations lists every chat between a shopper and Wes. Click a row to open the transcript + tool calls + products shown + outcome (purchased / abandoned / escalated). Flag a turn to feed training.

The transcript view

• Left pane — the actual chat as the shopper saw it.
• Right pane — the tool calls Wes made, their arguments, their results, and the turn latency each one contributed.
• Top bar — outcome + revenue attribution + which A/B variant was active.
• Teach Wes — correct any turn and the correction flows back into the next prompt compile.

Users management

Administration → Users. Three roles:

• super_admin — cross-tenant, manages tenants, users, system configuration.
• site_admin — full rights inside their tenant (your store).
• user — read-only by default; permissions granted explicitly (e.g. conversations.view, intents.edit).

Magento MCP — every built-in tool

The WisWes_MCP module (Composer package wiswes/module-mcp, source at github.com/wiswes/magento) ships 22 tools grouped into Catalog, Cart, Checkout, Customer, Sales, and Wishlist. See /install/magento for the full setup guide.

Extending MCP — write your own tool

Every Magento tool is a plain PHP class with a #[McpTool] attribute. Drop a new class into Mcp/Tool/…, decorate a public method, and it appears in your WisWes workspace after a recompile.

<?php
declare(strict_types=1);

namespace WisWes\MCP\Mcp\Tool\Sales;

use PhpMcp\Server\Attributes\McpTool;

class OrderTrackingTool
{
    public function __construct(
        private readonly \Acme\ThreePL\Api\TrackingClient $client,
    ) {}

    #[McpTool(
        name: 'sales-track-order',
        description: 'Returns carrier + tracking URL for an order. Arguments: order_id (string).'
    )]
    public function track(string $orderId): array
    {
        $shipment = $this->client->getLatestShipment($orderId);
        return [
            'order_id'     => $orderId,
            'carrier'      => $shipment->getCarrier(),
            'status'       => $shipment->getStatus(),
            'tracking_url' => $shipment->getTrackingUrl(),
        ];
    }
}

The name becomes the tool id. The description is what the model reads when deciding whether to call it — be specific about each argument, what the return shape is, and when not to use the tool.

Deploying the module

# 1. Install via Composer (recommended)
composer require wiswes/module-mcp

# 2. Enable and compile
bin/magento module:enable WisWes_MCP
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

The MCP endpoint is now live at https://<your-magento>/mcp, served by your existing Apache/PHP-FPM. Open Stores → Configuration → WisWes Chat → Install and click Install — Magento mints a shared secret and hands it to your WisWes tenant via redirect. Full step-by-step at /install/magento.