nivq-chat-widget

Embeddable NivQ chat experience as a framework-agnostic Web Component (<nivq-chat>). Drop it into any site — plain HTML, React, Angular, Vue — with one tag and get the NivQ chat UI in a floating launcher (FAB) or inline panel.

• Style-isolated — renders in a Shadow DOM; no CSS bleed in either direction.
• Secret-safe — never touches your OAuth2 clientSecret; it uses a short-lived token from your own token-broker endpoint (see below).
• Themeable — defaults to the NivQ brand; override palette, logo, radius.
• Lazy charts — the Vega rendering stack loads only when a turn returns a chart.

Quick start

Via CDN (jsDelivr) — no build step:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/nivq-chat-widget@1/dist/nivq-chat.js"
></script>
<nivq-chat agent-id="YOUR_AGENT_ID" api-base-url="https://api.nivq.ai" token-endpoint="/nivq-token">
</nivq-chat>

Or via npm (bundlers / React / Angular):

npm i nivq-chat-widget

import "nivq-chat-widget"; // registers <nivq-chat>; ships its own types

Pin the major (@1) for automatic patches without breaking changes.

Token broker (required)

The widget authenticates with a short-lived bearer token, never your clientSecret. Stand up one small endpoint on your backend that exchanges your NivQ credentials for a token and returns only { access_token, expires_in }:

// POST /nivq-token  (your backend) — authenticate YOUR user first, then:
const r = await fetch(`${process.env.NIVQ_API_BASE}/oauth2/token`, {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.NIVQ_CLIENT_ID,
    client_secret: process.env.NIVQ_CLIENT_SECRET, // stays server-side
  }),
});
const { access_token, expires_in } = await r.json();
res.json({ access_token, expires_in }); // never return the secret

The widget calls POST {token-endpoint}, caches the token, and refreshes it before expiry. Full Node/Spring examples, the CORS allow-list step, and the privacy notes are in docs/integration.md (shipped in the package).

CORS: the widget streams straight from the browser to api-base-url, so add the origin(s) you embed on to the API key's Allowed origins when you create it.

Configuration

| Attribute | Required | Default | Description | | ------------------ | -------- | -------------- | -------------------------------------------------------- | | agent-id | ✅ | — | The NivQ agent to chat with | | token-endpoint | ✅ | — | Your token broker URL | | api-base-url | ✅ | — | NivQ chat API base (e.g. https://api.nivq.ai) | | mode | | fab | fab (floating launcher) or inline | | target | | — | Inline only: CSS selector of the container to mount into | | position | | bottom-right | bottom-right or bottom-left (FAB) | | theme | | auto | light, dark, or auto (follows OS) | | locale | | auto | tr, en, or auto (browser language) | | primary-color | | NivQ red | Hex (#6d28d9) or HSL triplet (265 70% 50%) | | accent-color | | NivQ | Hex or HSL triplet | | radius | | 0.625rem | Corner radius (any CSS length) | | logo-url | | NivQ mark | Replace the brand logo | | brand-name | | NivQ | Header title / logo alt text | | launcher-label | | — | Text next to the FAB icon | | greeting | | — | Custom empty-state heading | | placeholder | | localized | Input placeholder text | | title | | localized | Panel header title | | external-user-id | | — | Distinguishes your end-user | | persist | | false | Persist the conversation in localStorage | | start-open | | false | FAB only: open the panel on load |

Programmatic config:

document.querySelector("nivq-chat").configure({
  primaryColor: "#6d28d9",
  brandName: "Acme Assistant",
  mode: "inline",
});

License

UNLICENSED — © Nivorbit. See https://nivq.ai.