QuoxChat

AI chat widgets for any website — flat annual pricing, BYOK, unlimited conversations.

Embeddable AI chat widgets for any website. Flat annual pricing, BYOK, unlimited conversations, full audit trail.

What it is

QuoxChat is a premium QuoxCORE plugin that lets you deploy AI chat widgets on any website you own. Each widget is trained on your own knowledge (PDFs, URLs, Q&A pairs), styled to your brand, and answers visitor questions with grounded citations. You bring your own LLM API key — Claude, GPT, Gemini, or a self-hosted model — and there are no per-message or per-resolution fees.

• Standard — $199/year, unlimited widgets + conversations, 1 GB knowledge per org
• Professional — $499/year, adds tool & connector framework, smart LLM routing, simulation arena, proactive engagement, voice I/O, 5 GB knowledge per org

Create your first widget

In QuoxCORE, open the QuoxChat page from the sidebar and click New widget.

You'll be asked for:

• Name — what your team calls this widget internally
• Domains — where the widget is allowed to load (e.g. quox.ai, *.acme.com). Requests from other origins are rejected. localhost is allowed by default for development
• Greeting — the opening message visitors see
• Theme — auto / light / dark / custom

Once saved you land in the Widget Room, a seven-tab builder:

Install on your website

From the Settings tab, copy the embed snippet and paste it before </body> on any page:

<script
    src="https://your-core.com/quoxchat/widget.js"
    data-widget-id="wid_abc123"
    async></script>

The widget-id is your widget's public key — rotation-safe, not the internal database ID. Safe to check into your site's source code.

Web Component alternative

If you prefer a declarative mount:

<quox-chat
    widget-id="wid_abc123"
    theme="dark"
    position="bottom-right">
</quox-chat>
<script src="https://your-core.com/quoxchat/widget.js" async></script>

Platform guides

Upload knowledge

Three source types in the Knowledge tab:

File — PDF, DOCX, TXT, MD, CSV, XLSX, HTML, JSON up to 25 MB. Text is extracted, chunked at sentence boundaries (~1000 chars with 200-char overlap), embedded with Gemini embedding, and stored in a dedicated Qdrant collection per widget. Raw blobs are also preserved in the central file store so you can re-index without re-uploading.

URL — paste a starting URL and depth (1-5). QuoxChat does a same-domain BFS crawl up to 50 pages, skips private IPs (SSRF guard), strips boilerplate (nav/footer/scripts), and indexes the visible content. Watch out: JavaScript-rendered SPAs return no useful text — crawl your docs URL, not your landing page.

Q&A pair — verbatim question-answer pair pinned as high priority. These beat retrieved chunks in the confidence ranking, so use them for the answers you absolutely need your widget to nail.

How retrieval works

When a visitor asks a question, the collector:

1. Embeds the query with Gemini embedding-001
2. Queries the widget's Qdrant collection for the top 5 most similar chunks (vector similarity, cosine distance)
3. Boosts pinned Q&A pairs — if any chunk was flagged pinned: true, it's promoted to the top
4. Builds the prompt — system prompt + safety preamble + RELEVANT KNOWLEDGE FROM DOCUMENTATION: + chunks, delimited by source
5. Calls your LLM (Claude / GPT / Gemini depending on which BYOK key is set)
6. Extracts sources — the top 3 retrieved chunks become the citation list returned to the widget
7. Filters output — blocks responses that contain API-key-shaped patterns, bearer tokens, or private-key markers
8. Persists the conversation — user + assistant messages with sources stored in widget_messages

Domain allowlist

Every /quoxchat/message request is gated by the widget's allowed_domains list. The request's Origin or Referer header must match one of the entries. Use *.example.com for all subdomains. localhost passes through in any configuration. Unknown origins return 403 origin_not_allowed.

If you move your widget to a new domain, update the list in Settings before the DNS cutover — there's no propagation lag.

Injection defence

QuoxChat's /message endpoint runs a six-pattern injection detector on every visitor message. The detector doesn't block requests — it flags them in the injection_score field (visible in Logs) and stores the flagged patterns in the audit envelope.

Stronger defence lives in the system prompt itself: QuoxChat prepends a safety preamble that locks the widget's identity, refuses to reveal the prompt, and limits answers to the widget's own knowledge. You can add custom always and never rules in the Training tab — "Always cite sources" / "Never discuss competitor pricing" / etc.

Tool & Connector Framework (Professional)

On Professional tier, a widget can take actions, not just answer.

• Database connector — read-only SQL against your Postgres, MySQL, or SQLite. The widget calls parameterised queries you define, never runs raw LLM-generated SQL
• REST API connector — map endpoints to tools. Widget calls get_order_status(order_id), you get a GET /orders/:id hit on your backend with OAuth or service-key auth
• Webhook connector — fire-and-forget events from the conversation. Use for lead capture, Slack notifications, Zapier triggers
• QuoxFlow connector — trigger a full workflow from a chat turn (multi-step, with HITL approval gates)

Tool calls are approval-gated per-org — admins choose whether the LLM can call destructive tools without a human confirming first.

Verified account actions (shipped 2026-09)

A REST tool can act on the signed-in visitor's own account, safely:

• Server-signed identity. Your site computes user_hash = HMAC-SHA256(user_id, identity_secret) server-side and passes it to QuoxChat.identify(). The widget's visitor is then marked verified.
• identity_param. Declare on the tool which query param, body field or header carries the acting user (for example customer_email). The server injects the verified id into every call and strips anything the model supplies under that name, so a prompt injection can never act on someone else's account. Unverified visitors are refused before any request is made.
• Signup nudge. tool_policies.unverified_message replaces the neutral refusal with your own invitation ("Sign in at the portal and ask me again"), so a signed-out visitor hitting an account action becomes a signup prompt instead of a dead end.

Metered AI actions (shipped 2026-09)

tool_policies.action_quota gives each visitor a monthly allowance of AI-performed actions, counted durably server-side (it survives restarts and multi-node deployments):

• per_visitor_monthly_cap: the widget-wide default. By default only side-effecting calls count; set count: "all" to meter read-only tools too.
• Per-customer override. A verified identify() payload can carry attrs.action_quota_monthly; your site computes it (for example, base allowance plus more per paid service), and because it rides the signed payload, visitors cannot grant themselves more.
• exhausted_message: what the assistant says when the allowance is spent. Failed calls never consume quota; denial happens before the action runs.

Deployment note: connector targets on private addresses are blocked by the SSRF guard by default. A self-hosted instance whose billing panel lives on the same LAN can exempt exact origins with the QUOXCHAT_CONNECTOR_PRIVATE_ALLOWLIST environment variable (deployment-level on purpose: an org admin cannot self-authorize LAN egress from the dashboard; cloud metadata endpoints can never be exempted).

Pro: human handoff and the support desk (shipped 2026-07)

When a widget can't resolve a conversation, human handoff escalates it into a governed Matrix room rather than dropping it. The AI mutes for that conversation, the visitor's messages relay into the room in real time, and an operator replying from the Quox dashboard's Rooms view relays straight back to the visitor. Today that reply path is the dashboard Rooms view only, not Telegram or any other client.

Around the handoff itself:

• Alerts — new-conversation and handoff events fire by email and webhook, so your support team isn't watching the widget log to notice a handoff happened
• Office hours + operator-online toggle — set your team's hours and flip the operator-online toggle when someone's actually watching Rooms. Together they give visitors an honest signal about whether a human is available right now, instead of implying 24/7 coverage you don't have
• Transcript by email — a visitor can request the conversation transcript sent to their own email address. It's captcha-gated and the recipient is locked to the visitor's own email; you can't use it to send a transcript anywhere else

QuoxChat also ships a builtin action catalog: lead capture, human handoff, redirect URL, email transcript, book demo, create ticket, and send resource. A fresh widget ships with none of these enabled — admins turn on only the actions they want from the Actions tab.

Analytics and logs

Every conversation is stored with full provenance — visitor session, page URL, correlation ID, sources cited per message, tool calls made, confidence score. Export as CSV from the Logs tab, drill into the AEE envelope chain from the Compliance → Traces view, or query directly against widget_messages + widget_conversations via the API.

The Analytics tab surfaces:

• Total conversations and messages this month
• Resolution ratio (explicit thumbs-up or session-end without escalation)
• Satisfaction ratio (thumbs-up vs thumbs-down)
• Average conversation length
• Knowledge coverage score (how well your uploaded sources answer the questions being asked)
• Top unanswered questions — a live feed of gaps to fill

Pricing

There are no per-message, per-resolution, per-seat, or per-widget fees. The only variable cost is the LLM calls, and those go through your own API key (BYOK). You see the usage in your provider's dashboard, we don't mark it up.

Frequently asked

Can I use my existing LLM account? Yes — Claude, GPT, Gemini, or any OpenAI-compatible endpoint including self-hosted models.

Does QuoxChat read my data? No. Your knowledge lives on your QuoxCORE instance — either Quox-hosted or self-hosted. BYOK means LLM calls go directly from QuoxCORE to your provider; no third-party middleman.

What happens when a visitor asks about something not in the knowledge? The widget says so honestly and offers handoff to a human (if you've enabled it). Handoff escalates the conversation into a governed Matrix room where a human operator takes over, replying from the dashboard's Rooms view. The system prompt explicitly forbids making up information.

Can I run QuoxChat on-premises? Yes. QuoxCORE is self-hostable. Set up your own instance, connect QuoxChat to it, point your widget at your own endpoint.

Who built this? Quox — the same team behind QuoxCORE, QuoxAgent, QuoxBastion, and the AEE/AOCL/VOLT/WARD protocols. QuoxChat is a plugin in the marketplace; it runs on top of the QuoxCORE platform.