supportbot-widget

Embeds the SupportBot chat widget using your existing widget.js and /chat backend. Works in React via <SupportBotWidget /> or in plain JavaScript via loadSupportBotWidget().

Customizations supported:

• Button type: icon or text
• Button content: emoji/icon or text string
• Button size: diameter (e.g. 48px, 64px)

Install

npm install supportbot-widget

React Usage (Local Dev)

import { SupportBotWidget } from "supportbot-widget"

function App() {
  return (
    <>
      {/* your app */}
      <SupportBotWidget
        tenantKey={import.meta.env.VITE_SUPPORTBOT_TENANT_KEY as string}
        widgetSrc={import.meta.env.VITE_WIDGET_SRC as string}
        cssHref={undefined}
        brandName="Demo Support"
        theme={{ primaryColor: "#4f46e5", radius: "12px", colorScheme: "auto" }}
        language="en"
        button={{ type: "icon", content: "💬", size: "64px" }}
        placement="bottom-right"
      />
    </>
  )
}

Plain JS Usage (Local Dev)

import { loadSupportBotWidget } from "supportbot-widget"

loadSupportBotWidget({
  tenantKey: import.meta.env.VITE_SUPPORTBOT_TENANT_KEY as string,
  widgetSrc: import.meta.env.VITE_WIDGET_SRC as string,
  brandName: "Demo Support",
  theme: { primaryColor: "#4f46e5", radius: "12px", colorScheme: "auto" },
  language: "en",
  button: { type: "text", content: "Support", size: "52px" },
  placement: "bottom-left"
})

### .env suggestions (Vite)

Create `.env.local` (excluded from VCS) and define:

VITE_SUPPORTBOT_TENANT_KEY=your_tenant_api_key VITE_WIDGET_SRC=http://localhost:5173/widget.js

Never commit `.env.local`. In production, inject these via your CI/CD or host provider secrets. If you must avoid exposing the tenant key to clients, render the script tag server-side and proxy `/chat` calls with a server-stored key.

### Security Notes
- Do not hardcode `tenantKey`, API host, or widget URL in source files.
- Use `.env.local` for local dev; use deployment secrets for staging/production.
- If your use case requires hiding the tenant key entirely, serve the widget script tag from your server and proxy `/chat` calls so the key never appears in client code.

## Script Tag Usage (CDN)

```html
<script
  src="https://cdn.supportbot.io/widget.js"
  data-tenant-key="TENANT_API_KEY"
  data-button-type="icon"      <!-- 'icon' | 'text' -->
  data-button-content="💬"      <!-- emoji/icon or text string -->
  data-button-size="64px"       <!-- diameter -->
  data-button-placement="bottom-right"
  data-language="en"
></script>

Alternatively via a global config object (set before the script loads):

<script>
  window.SupportBotWidgetConfig = {
    tenantKey: "TENANT_API_KEY",
    brandName: "Your Brand",
    theme: { primaryColor: "#4f46e5", radius: "12px", colorScheme: "auto" },
    language: "en",
    button: { type: "icon", content: "💬", size: "64px" },
    placement: "bottom-right"
  }
</script>
<script src="https://cdn.supportbot.io/widget.js"></script>

## Notes
- `widget.js` and `widget.css` should be served locally (e.g. your Vite dev server). Set `widgetSrc`/`cssHref` to the correct origin (for example `http://localhost:5173/widget.js`).
- The package sets `window.SupportBotWidgetConfig`, injects `widget.js` once per page (checks `data-supportbot-script="true"`), and optionally injects `widget.css`.
- The cleanup function removes only the nodes it injected.
 - Button customization is read from `window.SupportBotWidgetConfig.button` or from script tag `data-button-*` attributes.
 - Supported button types: `icon`, `text`, `hidden`, `custom`.
- Set `placement` to `bottom-right` or `bottom-left`.
 - Theme: set `theme.colorScheme` to `light`, `dark`, or `auto`.
 - Language: set `language` (e.g. `en`, `ar`, `fr`, `es`). This flows to the backend and influences AI replies.

## Reset

- In-widget: there is a "Restart" button inside the chat panel that clears the session and returns to the details step.
- Programmatic: you can trigger a reset from your app code via the global API:

```ts
// after widget has loaded
window.SupportBotWidget?.reset?.()
// optional helpers also available
window.SupportBotWidget?.open?.()
window.SupportBotWidget?.close?.()

Closed Sessions

When an agent marks a chat as done/answered, the backend closes the session:

• Further send attempts from the widget receive an HTTP 409 and the widget prompts the user to press Restart to begin a new chat.
• Public polling for messages may return 404 for closed sessions, which causes the widget to stop polling and show a friendly end-of-chat notice.

This ensures users cannot continue posting messages into an ended conversation and are guided to start a fresh session.

Inactivity, Theme Modes, and Language

• Auto dark mode: with theme.colorScheme: 'auto' the widget follows the OS preference and switches live.
• Language defaults: Admins can set a default language in Dashboard → Settings. The widget can override via config; backend stores per-chat language and AI answers in that language.
• Inactivity: widget resets after 30 minutes of inactivity and prompts again for user details.
• Platform/tenant disable: if disabled, the public widget will not render.