message.comDevelopers
Developers/AI/Knowledge base

AI knowledge base Live

The knowledge base supplies relevant business information to Message AI. Onboarding reuses your website to prepare answers; you can review the imported content and correct missing details. Knowledge-backed workflows retrieve relevant passages, while other tasks may use conversation context or authorized tools.

This is the retrieval half of retrieval-augmented generation. See the RAG concept page for why grounding matters and how it differs from fine-tuning.

The crawl

The URL-ingestion API below fetches public HTML on the same origin. Its defaults are 20 pages and one level of links from the starting page. The onboarding scan has its own workflow; these API defaults do not describe every connector. Error pages and pages that disallow indexing are excluded.

  • For this API, maxPages accepts 1–200; the default is 20.
  • maxDepth accepts 0–3; the default is 1, with the starting page at depth 0.
  • HTML only; PDFs and uploaded files use a separate ingestion path.
  • Request another ingestion job when your source content changes.

Chunking

The HTML ingestion path removes common navigation and boilerplate, extracts text and splits it into overlapping passages. Workspace defaults target roughly 500 tokens per passage with 50 tokens of overlap. Source URLs and titles help you inspect where an answer came from.

Embedding

Message generates embeddings to compare a question with imported passages. Successful import and indexing are separate from the quality of the original text: test representative customer questions after indexing completes.

Storage

Retrieval is scoped to the authenticated workspace. Superseded documents and non-public authored articles are excluded from customer-facing retrieval. Connector content also requires the matching site context and an eligible connected source.

Managing the KB via API

Use the dashboard for normal setup. The routes below require an authenticated workspace session: URL ingestion requires an administrator, and retrieval requires an authenticated agent. Keep these credentials on your server; they are not public browser-widget endpoints.

Crawl a URL

Queues an async ingestion job: crawl, chunk, and embed. There is no separate "source" resource to create first; posting a URL both registers it and starts the crawl.

cURL
curl -X POST 'https://app.message.com/api/v1/kb/ingest/url' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://acme.com",
    "maxPages": 200,
    "maxDepth": 2
  }'

// 200 OK. crawl runs async; poll GET /api/v1/kb/jobs/:id for status
{ "jobId": "uuid", "status": "queued" }

This authenticated endpoint returns relevant passages for the workspace. It does not accept a siteId, so site-scoped connector content is not included through this route. The example asks for five matches; omitted topK defaults to eight.

cURL
curl -X POST 'https://app.message.com/api/v1/kb/retrieve' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "How do I cancel my subscription?",
    "topK": 5
  }'
200 OK
{
  "chunks": [
    {
      "chunkId": "uuid",
      "documentId": "uuid",
      "chunkIndex": 3,
      "text": "To cancel, open Settings -> Billing -> Cancel...",
      "score": 0.87,
      "title": "Cancelling your subscription",
      "sourceUrl": "https://acme.com/help/cancel",
      "sourceType": "url",
      "articleId": null,
      "provenance": null
    }
  ],
  "queryEmbedTimeMs": 42,
  "searchTimeMs": 11
}

How AI uses retrieval

  1. A visitor sends a message. The AI workflow runs.
  2. We embed the visitor message with the same self-hosted embeddings model.
  3. The workflow retrieves passages scoped to the workspace and, where supported, the site.
  4. Relevant passages and conversation context inform the response.
  5. The workflow drafts a reply using the available information; source presentation depends on the channel.

Configure handoff behavior for questions the available knowledge cannot support. Grounding helps reduce unsupported answers, but it is not an accuracy guarantee. Test missing-information cases and sensitive requests before enabling autonomous replies.

Freshness

Do not assume a monthly refresh. Re-post a URL to POST /api/v1/kb/ingest/url when it changes, and inspect the returned job until it succeeds. Confirm updated passages through retrieval before relying on new prices, hours or policies.

CMS integrations

WordPress and Shopify connections can supply supported public content as knowledge sources. Check the source status and last successful import in Message.com before relying on a recent change. Import, analysis and indexing take time; publishing a page does not guarantee it is available to AI within a fixed number of seconds.

Common pitfalls

  • JavaScript-rendered content. This URL-ingestion route fetches HTML; it does not execute client-side JavaScript. Provide accessible HTML or use a supported content connector. Authenticated pages cannot be imported through this public-URL route.
  • Stale answers. If your KB hasn't been recrawled since a pricing change, the AI may quote old prices. Trigger a recrawl on launch.
  • Empty chunks. Pages with little useful text may not produce useful passages. Inspect the ingestion job and imported content rather than assuming every discovered page became knowledge.