business-chat-widget

Embeddable AI chat widget for React. It renders a floating launcher button that opens a chat panel — or an always-open panel embedded in your page with mode="inline" — and talks to your own API: the browser never calls the AI provider directly and never holds an API key. Bring any backend that implements a small request contract.

• No UI/CSS framework dependencies; hand-written CSS (every class prefixed bc- to avoid collisions).
• React 18+ as a peer dependency (not bundled).
• Localized English/Spanish defaults, fully overridable through props.
• Theming through --bc-* CSS variables.

Install

npm install business-chat-widget

react and react-dom (18+) are peer dependencies.

Usage

import { BusinessChat } from 'business-chat-widget';
import 'business-chat-widget/styles.css';

<BusinessChat
  apiEndpoint="https://your-api.example.com/chat"
  language="en"
  businessInfo={{
    name: 'Acme Studio',
    description: 'We build websites and AI tools for small businesses',
    services: ['Landing pages', 'Online stores'],
    tone: 'casual', // | 'formal'
    contactMethods: [
      {
        type: 'whatsapp',
        value: '+1 555 0100',
        href: 'https://wa.me/15550100',
        useFor: ['quote', 'general'],
        primary: true,
      },
    ],
  }}
  systemPrompt="Answer in English unless the visitor asks otherwise"
  greeting="Hi! Ask me about our services."
  theme={{ primaryColor: '#2563eb' }}
/>;

Spanish defaults are available with the same component:

<BusinessChat
  apiEndpoint="https://your-api.example.com/chat"
  language="es"
  businessInfo={{
    name: 'Estudio Acme',
    description: 'Hacemos páginas web y herramientas de IA para pequeñas empresas',
    services: ['Landing pages', 'Tiendas en línea'],
    tone: 'casual',
    contactMethods: [
      {
        type: 'whatsapp',
        value: '+52 81 1234 5678',
        href: 'https://wa.me/528112345678',
        useFor: ['quote', 'general'],
        primary: true,
      },
    ],
  }}
  systemPrompt="Responde en español a menos que el visitante pida otro idioma"
  greeting="¡Hola! Pregúntame sobre nuestros servicios."
/>;

API contract

The widget builds systemPrompt from businessInfo, the selected language, and your optional extra business context, then calls apiEndpoint:

POST { messages, systemPrompt } -> { reply }

messages is the conversation so far ({ role, content }[]) and reply is the assistant's complete response (no streaming in v1). Treat browser-supplied systemPrompt as lower-priority business context; non-negotiable safety or capability rules should be enforced on the server. Keep your AI provider key on the server side; it must never reach the browser.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiEndpoint | string | - | API URL (required) | | businessInfo | BusinessInfo | - | Business name, description, services, tone, and contact methods (required) | | conversationKey | string \| number | - | Change this value to reset in-memory messages for a new business, language, or context | | language | 'en' \| 'es' | 'en' | Localized defaults for UI labels and generated prompt text | | systemPrompt | string | - | Extra business context appended with lower priority than server-side safety rules | | title | string | Assistant / Asistente | Header title and launcher label | | placeholder | string | Write your message... / Escribe tu mensaje... | Input placeholder | | greeting | string | - | Optional welcome message shown while the chat is empty | | sendLabel | string | Send / Enviar | Accessible label for the send button | | disclaimer | string | localized default | Short AI notice shown near the input | | showDisclaimer | boolean | true | Set to false to hide the AI notice | | errorMessage | string | localized default | Text shown when the request fails | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Corner where the launcher and chat window are anchored (floating mode only) | | mode | 'floating' \| 'inline' | 'floating' | 'floating' shows a corner launcher; 'inline' embeds the always-open panel in the page flow | | theme | Theme | - | Colors and sizing (see below) |

Explicit text props always override the language defaults.

businessInfo.contactMethods lets the prompt recommend the right contact channel for appointment, quote, reservation, support, or general contact requests without claiming the business has confirmed an external action. Supported method types are whatsapp, phone, email, url, address, and custom; supported use cases are appointment, quote, reservation, support, and general.

By default, the chat footer shows a short localized notice that AI can make mistakes and important information should be verified. Override it with disclaimer or hide it with showDisclaimer={false}.

When the host app swaps the active business or language without unmounting the widget, pass a stable conversationKey. Changing it starts a fresh in-memory conversation and ignores any late response from the previous context.

Inline (embedded) mode

mode="inline" renders the chat panel directly in the page flow instead of a floating corner widget: no launcher, no close button, always open, and it never steals focus on page load. The panel fills the width of its container; its height defaults to 540px and can be changed with theme.inlineHeight (or the --bc-inline-height CSS variable on any ancestor).

<div style={{ maxWidth: 420 }}>
  <BusinessChat
    mode="inline"
    apiEndpoint="https://your-api.example.com/chat"
    businessInfo={{ name: 'Acme Studio', description: 'We build websites' }}
    theme={{ inlineHeight: '600px' }}
  />
</div>

Mobile on-screen keyboard

In floating mode the widget tracks window.visualViewport while open, so when the on-screen keyboard appears (including iOS Safari, which never resizes the layout viewport) the chat window shrinks to the visible area and the input stays in view. No host-page changes or viewport meta additions are needed.

Theming

The theme prop maps to CSS variables. You can also override them directly in CSS:

| Variable | Prop | Default | |----------|------|---------| | --bc-primary | primaryColor | #6366f1 | | --bc-bg | backgroundColor | #ffffff | | --bc-text | textColor | #1f2937 | | --bc-radius | borderRadius | 16px | | --bc-font | fontFamily | system-ui | | --bc-z | zIndex | 9999 | | --bc-inline-height | inlineHeight | 540px (inline mode only) |

All widget classes use the bc- prefix to avoid collisions with host-site CSS.

License

UNLICENSED — all rights reserved.