Documentation

Overview

MatchWiser is an AI lead qualification widget you embed on your website. Visitors open a chat, the AI qualifies them naturally, and only the best-fit leads receive your call-to-action.

The system has two parts:

Quick start

From purchase to live widget in under 15 minutes.

Embedding the widget

Add a container element and the widget script to your HTML. Everything below is pre-filled in your download — you only need to copy and paste.

1. Add a container

Place an empty <div> where you want the widget to appear. The id must match containerId in your config.

<div id="my-widget"></div>

2. Load the script and initialise

<script src="/matchwiser.iife.js"></script>
<script>
  MatchWiser.init({
    widgetId:    "your-widget-id",
    propId:      "your-prop-id",
    widgetToken: "your-widget-token",
    containerId: "my-widget",
    name:        "Your Company",
    mode:        "embedded",
    language:    "en",
    llm: {
      provider: "anthropic",
      model:    "claude-sonnet-4-6",
      proxyUrl: "https://your-proxy.railway.app",
    },
    theme: {
      primaryColor: "#8833FF",
      colorScheme:  "dark",
    },
    // ... rest of your generated config
  });
</script>

Deploying the proxy

The proxy is a Node.js (Express) server included in your download as a Railway-ready template. It acts as a secure intermediary between your widget and the LLM provider — your API key stays on the server, never in the browser.

Deploy to Railway

Environment variables

Set these in your Railway project's Variables tab (or in a .env file for local development).

Widget options

The full list of fields accepted by MatchWiser.init(). All required fields are generated for you during onboarding.

Root

theme

flow

Lead webhooks

When a visitor qualifies (or clicks your CTA), the proxy can POST the lead data to any URL you control — your CRM, a Slack webhook, Airtable, Make, Zapier, or your own endpoint. Set the LEADS_WEBHOOK_URL environment variable on your proxy to enable it.

Payload

{
  "event": "lead.qualified" | "lead.converted",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "widgetId": "...",
  "sessionId": "...",
  "company": {
    "name": "Acme Inc.",
    "domain": "acme.com",
    "industry": "Software",
    "employeeCount": 120,
    "country": "US",
    "technologies": ["React", "Salesforce"]
  },
  "qualification": {
    "fitResult": "qualified" | "unqualified" | "unknown",
    "matchedSignals": ["company size", "industry"],
    "missingSignals": []
  }
}

The lead.qualified event fires when the AI determines the visitor matches your ICP. lead.converted fires when the visitor clicks your CTA button.

Signature verification

Set LEADS_WEBHOOK_SECRET on your proxy to sign every request. Each delivery will include an X-MatchWiser-Signature header containing an HMAC-SHA256 of the raw request body. Verify it on your endpoint to confirm the payload came from your proxy and was not tampered with.

Knowledge base

Pass URLs in flow.knowledgeBaseUrls to give the AI access to product-specific information. The proxy fetches each URL at session start, strips the HTML, and injects the plain text into the AI's system prompt.

Good URLs to include

• Your product features or use-cases page
• Pricing page
• FAQ or support page
• Case studies or customers page
• Integration or API documentation

Limits

Language support

MatchWiser supports multilingual conversations. Set a default language for the AI's opening messages — it automatically switches to whatever language your visitor uses.

Setting the default language

MatchWiser.init({
  // ...
  language: "pt-BR",   // opens in Brazilian Portuguese
});

Supported languages

Updating your widget

There are two kinds of updates: changing your configuration and updating the widget JS version. Both can be done at any time without re-purchasing.

Updating your configuration

Your configuration lives entirely inside the MatchWiser.init({ ... }) call in your HTML. Edit it directly — change the greeting, update your ICP description, adjust colors, add knowledge base URLs. The change takes effect on the next page load with no re-deployment required.

Updating the JS file

When a new version of the widget is available, replace matchwiser.iife.js on your server with the new file. No configuration changes are required unless the release notes say otherwise.

Updating the proxy

The proxy source code is included in your download. When a new proxy version is released, update the files in your GitHub repo and Railway will redeploy automatically.

FAQ