👁 Image
Umbraco.Community.AI.Chatbot.Persistence 1.0.0

Umbraco.Community.AI.Chatbot

A community Umbraco package that exposes a public-facing, AI-powered chat widget on a website's frontend. Visitors ask questions in natural language; the package runs a semantic search over your site's content (Umbraco.AI.Search), feeds matched pages into an Umbraco.AI.Agent, and streams a grounded answer back with cited source pages and follow-up suggestions.

Requirements

• Umbraco CMS 17.3+
• Umbraco.AI 1.10+
• Umbraco.AI.Agent 1.9+ — at least one configured Agent
• Umbraco.AI.Search — a populated index over your site's content

Quickstart

1. Install the NuGet package in your Umbraco site project.

2. Build the search index under AI → Add-ons → Search — the chat package reads from UmbAI_Search.

3. Create an Agent under AI → Add-ons → Agents. Put your brand voice / persona in the agent's Instructions field.

4. Create a Chat Instance under AI → Add-ons → Chatbot → Create. Pick the agent you just made, set a welcome message and a fallback message.

5. Drop the widget script into the public layout (e.g. Views/Master.cshtml):

   <script type="module"
    src="/App_Plugins/UmbracoCommunityAIChatbot/widget.js"
    data-instance="my-chat-alias"></script>
   

   Optional attributes:

   • data-welcome="..." — overrides the welcome message configured in the backoffice
   • data-title="..." — overrides the panel title
   • data-api-base="..." — only needed for cross-origin embedding

A floating chat button appears bottom-right on every page that includes the script.

How it works

Website visitor
 │ POST /umbraco/community/chatbot/api/v1/chat (anonymous, SSE)
 ▼
ChatController ── rate limit + agent-active check
 ▼
ChatOrchestrator
 ├── ISearcher → top-K matched documents
 ├── ContentResolver → IPublishedContent → title, URL, body text
 ├── GroundingPromptBuilder → strict "answer ONLY from sources" prompt
 ├── IAIAgentService.StreamAgentAsync → streamed answer (uses agent's Instructions)
 └── FollowUpGenerator → suggested follow-up questions
 ▼
SSE: sources → delta* → suggestions → done

The agent's persona/tone lives on the agent's Instructions field. Our orchestrator only owns the grounding rules and the source block — so the two prompts don't fight.

Configuration

Each chat instance has:

Migrations run automatically on application start.

Rate limit (public endpoint)

The public chat endpoint is anonymous and LLM-backed, so by default we apply a per-IP sliding-window limit of 30 requests / 5 minutes. Override in appsettings.json:

{
 "Umbraco": {
 "Community": {
 "Chatbot": {
 "RateLimit": {
 "RequestsPerWindow": 30,
 "WindowSeconds": 300
 }
 }
 }
 }
}

Set RequestsPerWindow to 0 to disable. Tighten it on production sites that don't expect heavy traffic — there's no practical reason a single visitor needs more than a handful of chat turns per minute.

Per-request size caps are also enforced: max 50 messages in the conversation, max 4 000 characters per message. Exceeding either returns a 400.

⚠️ Security caveats — read before deploying

Anonymous LLM access costs money

Even with the rate limiter on, a determined attacker behind a botnet can still drive up your inference bill. If you have any concern about this, put a CDN/WAF in front (Cloudflare Turnstile, AWS WAF rate rules, etc.) and consider a tighter RequestsPerWindow.

Member-protected content

The chat endpoint is anonymous. The package's IChatPrincipalAccessor is wired but ships an anonymous-only implementation. If your search index contains member-protected content, all of it is reachable through the public chat. Until a Member-aware accessor lands, the safe path is to keep member-only documents out of the UmbAI_Search index, or build a custom IChatPrincipalAccessor that maps the cookie member into the access context.

XSS posture

The widget renders the model's response through marked and unsafeHTML. The model is grounded in your own published content, so practical XSS surface is small — but if you index user-generated text (comments, forum posts), pipe model output through DOMPurify before rendering or strip HTML tags entirely.

Things explicitly not in MVP

• Server-side conversation history / analytics — the widget owns history in localStorage, capped at 20 turns
• Multi-instance scoping by content sub-tree
• Member-aware content filtering implementation (the abstraction is wired)
• SignalR (we use SSE)
• Cross-origin (CORS) embedding — assume same-origin

License

MIT — see .