Live on your site in two lines

1. 1

   Add your content. Point the crawler at your site in the Knowledge tab. Everything the assistant will ever say comes from what you index here, so it is worth reviewing the source list once the first crawl finishes.

2. 2

   Paste the snippet. Two lines before the closing body tag. Nothing to install, no package, no build step.

3. 3

   Lock it down. Add your domains to the allow-list and set a daily cap before you publish. Both take a minute and neither can be added retrospectively to a bill.

<!-- Matter Chat — paste right before </body> -->
<script>
  window.MatterChat = window.MatterChat || { q: [] };
  window.MatterChat.q.push(["init", { id: "YOUR_BOT_KEY" }]);
</script>
<script async src="https://app.matterchat.co/widget/7e4105892a01.js"
  integrity="sha384-Ad9fQNB21lekRAm92bhT3xTEgdh8/x6L0usYOaBWYEB/S+cSy6r+EvgUepDSnjR0"
  crossorigin="anonymous"></script>

The snippet pushes onto a queue rather than calling a function directly, which is why the order of the two script tags does not matter and why nothing breaks if the widget script is still loading when your page finishes.

All options together

window.MatterChat = window.MatterChat || { q: [] };
window.MatterChat.q.push(["init", {
  id: "YOUR_BOT_KEY",
  title: "Acme Support",
  greeting: "Ask about shipping, returns, or sizing.",
  accent: "#0F9D6B",
  position: "right",
}]);

1. 1

   Set the domain allow-list. Add every domain the widget runs on — subdomains count separately, so acme.com and www.acme.com are two entries. An empty list means any site can use your bot key.

2. 2

   Set the daily reply cap. How many answers the bot may give in a day. When it is reached the widget pauses politely rather than continuing to spend. Set it above a normal day and below what you would be unhappy to pay on the worst one.

3. 3

   Review what was actually crawled. Open the source list. You are looking for important pages that are missing, and noise that should not be there — tag archives, pagination, or an old staging domain.

4. 4

   Ask it ten hard questions. Use the dashboard test chat, and check the citation on each answer rather than only the answer. A correct answer citing an unrelated page means retrieval got lucky and the next question will not.

Ask a question — POST /api/v1/query

curl -X POST https://app.matterchat.co/api/v1/query \
  -H "Authorization: Bearer mc_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"botId": "YOUR_BOT_ID", "question": "Do you ship internationally?"}'

Response

{
  "answer": "Yes — we ship to most of Europe and North America...",
  "sources": [
    { "n": 1, "title": "Shipping & delivery", "url": "https://acme.com/shipping" }
  ],
  "grounded": true
}

grounded: false means nothing relevant was found. When that happens answer is null and sources is empty — no answer is invented to fill the gap. Treat it as a refusal and route it the way you would route one in the widget.

Add or refresh a page — POST /api/v1/ingest

curl -X POST https://app.matterchat.co/api/v1/ingest \
  -H "Authorization: Bearer mc_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"botId": "YOUR_BOT_ID", "url": "https://your-site.com/new-page"}'

Response

{
  "sourceId": "src_...",
  "chunkCount": 12,
  "skipped": false,
  "error": null
}

skipped: true means the page content has not changed since the last ingest, so nothing was re-indexed. Calling this after a deploy is safe and cheap — unchanged pages cost nothing.

A 429 is not always a rate limit. It is also returned when the bot has hit its daily cap, its daily message limit, or the workspace's monthly allowance — so back off and retry only when the message says the rate limit. The other three will not clear in a few seconds.

Widget traffic is bounded separately, by your per-visitor rate limit and the bot's daily reply cap. Those are set per bot in the dashboard rather than here, and they apply whether or not you use the API.

Subdomains are separate origins. acme.com and www.acme.com are two allow-list entries, and forgetting the second is the most common reason a widget works locally and not in production.