@keyon/chat-widget

Embeddable sales-chat widget for Keyon property microsites. Two ways in.

1. Script tag — no build step

For a microsite that is plain HTML. React is bundled; nothing else to install.

<script
  src="https://your-cdn/keyon-widget.js"
  data-project="la-valora"
  data-api-url="https://chat.keyon.in"
  data-theme-color="#b4735a"
  data-title="La Valora"></script>

That's the whole integration. It mounts a floating launcher on load.

2. React package

npm install @keyon/chat-widget

import { KeyonChatEmbed } from "@keyon/chat-widget";

<KeyonChatEmbed
  project="la-valora"
  apiUrl="https://chat.keyon.in"
  themeColor="#b4735a"
  title="La Valora"
/>

Use KeyonChatEmbed (shadow DOM) unless you control the page's CSS entirely, in which case KeyonChat renders without the boundary.

Options

| Prop | data- attribute | Default | | |---|---|---|---| | project | data-project | — | Required. Project slug the backend knows. | | apiUrl | data-api-url | — | Required. Backend base URL. | | themeColor | data-theme-color | #b4735a | Brand accent. The rest of the palette is derived. | | textColor | data-text-color | auto | Text on the accent — header, launcher, visitor bubbles. Auto-picked for contrast if omitted. | | title | data-title | Chat with us | Header text. | | launcherLabel | data-launcher-label | Chat with us | Closed-state button label. | | placeholder | data-placeholder | Ask about the project… | Composer placeholder. | | position | data-position | bottom-right | or bottom-left. | | inline | data-inline | false | Render in page flow instead of floating. | | defaultOpen | data-default-open | false | Open on mount. | | theme | data-theme | light | light | dark | auto. | | radius | data-radius | 16 | Corner radius in px. | | target | data-target | appended to body | CSS selector to mount into. |

Programmatic mounting, for multiple instances or conditional loading:

const unmount = KeyonChat.mount({
  project: "la-valora",
  apiUrl: "https://chat.keyon.in",
  themeColor: "#2f6f4e",
  inline: true,
  target: "#chat-slot",
});

Two colours, not eight

You give themeColor; hover state and tinted bubbles are computed from it.

The text that sits on the accent is auto-picked by WCAG contrast rather than assumed to be white — a pale brand colour with white label text is the most common embed bug. That maths sometimes disagrees with a brand guideline (#1877f2 scores higher with black than white), so textColor overrides it. An override is always honoured; if it falls below 3:1 against the accent, or isn't valid hex, the widget warns in the console and carries on.

Style isolation

Everything renders inside a shadow root with all: initial on the host. Microsites ship global resets, * { box-sizing } rules, utility classes and !important overrides; without a hard boundary the widget inherits whatever the page does to button and input and looks broken on a site nobody tested against. demo/index.html deliberately forces Comic Sans and red dashed borders on every button and textarea to prove the boundary holds.

Backend requirements

The widget sends credentials: "include" so the session cookie round-trips and a conversation stays one thread. That requires the server to name the embedding origins explicitly — the CORS spec forbids wildcard-plus-credentials, and browsers drop the cookie silently rather than erroring:

CORS_ORIGINS=https://la-valora-hyderabad.com,https://another-microsite.in

Endpoints used: GET /greeting, POST /chat (SSE).

Development

npm install
npm run build          # dist/index.js, dist/index.cjs, dist/keyon-widget.js

python3 -m http.server 5500      # then open /demo/index.html

The demo points at http://127.0.0.1:8000; add http://127.0.0.1:5500 to CORS_ORIGINS on the backend.