@flowengage/react-chatbot

Embeddable AI-powered customer support chat widget — built by FlowEngage.
Add live chat, AI assistant, and agent handoff to any site in minutes. All you need is your Site ID.

Choose how to integrate

| Approach | Best for | What you add | |----------|-----------|--------------| | npm package | React, Next.js, Vite, Remix, etc. | Install the package, wrap your app with FlowEngageProvider, render FlowEngageWidget. | | CDN (script tag) | Plain HTML, PHP, WordPress, Drupal, non-React SPAs | One <script> tag; styles are bundled into the embed — no separate CSS file. |

You need a Site ID from the FlowEngage dashboard (Integration Guide or site settings).

A. npm package (React / Next.js / Vite)

Prerequisites

• React 18+ and react-dom 18+ in your project (peer dependencies).
• Node 18+ recommended for local development.

1. Install

npm install @flowengage/react-chatbot

# or
yarn add @flowengage/react-chatbot
pnpm add @flowengage/react-chatbot

Pin a version in production if you prefer reproducible builds:

npm install @flowengage/react-chatbot@^1.0.0

2. Import the stylesheet once

The widget ships its own CSS. Import it at your app entry (or a layout file):

import '@flowengage/react-chatbot/styles.css';

3. Wrap your app and mount the widget

FlowEngageProvider must wrap any component that uses FlowEngageWidget or useFlowEngage.

// e.g. App.jsx, main.jsx, or a root layout wrapper
import { FlowEngageProvider, FlowEngageWidget } from '@flowengage/react-chatbot';
import '@flowengage/react-chatbot/styles.css';

export default function App() {
  return (
    <FlowEngageProvider siteId="YOUR_SITE_ID">
      <YourExistingApp />
      <FlowEngageWidget />
    </FlowEngageProvider>
  );
}

Next.js App Router

• Put the provider + widget in a Client Component (file with "use client" at the top), or a client wrapper imported from layout.tsx.
• Keep a single provider tree so chat state is shared.

Yarn / monorepo

Ensure the package resolves once at app level so you do not mount duplicate providers.

Dashboard styling vs code (widgetSettings)

Use only siteId (and optional apiBaseUrl for local dev) on FlowEngageProvider so the widget loads branding, theme, greetings, and recommendations from the FlowEngage dashboard on every page load—same as the CDN embed.

If you also pass config={{ widgetSettings: { ... } }}, those fields act as defaults only; saved dashboard settings override them. Avoid pasting a full widget JSON into your app unless you intentionally want offline defaults; otherwise you would have to update code after each dashboard change.

B. CDN / script tag (no React project required)

The embed build includes React and injects styles automatically. You do not import styles.css when using the script.

B1. FlowEngage CDN (recommended)

Use the hosted script (kept in sync with FlowEngage infrastructure):

<script
  src="https://cdn.flowengage.com/flowengage-embed.js"
  data-site-id="YOUR_SITE_ID"
  defer>
</script>

Place this before </body> on every page where the widget should appear, or in your global theme template.

B2. npm registry CDN (pin a version)

If you prefer to load the same artifact published to npm (useful for pinning or offline mirrors):

<!-- Replace 1.0.0 with the version you want -->
<script
  src="https://cdn.jsdelivr.net/npm/@flowengage/[email protected]/dist/flowengage-embed.js"
  data-site-id="YOUR_SITE_ID"
  defer>
</script>

Equivalent path on unpkg:

https://unpkg.com/@flowengage/[email protected]/dist/flowengage-embed.js

Auto-init attributes (data-*)

On the <script> tag:

| Attribute | Required | Description | |-----------|----------|-------------| | data-site-id | ✅ for auto-init | Your Site ID from the dashboard. | | data-api-url | ❌ | Override API base URL (advanced; usually omit). | | data-widget-settings | ❌ | JSON string of runtime widget overrides (theme, branding). Example: '{"theme":{"primaryColor":"#2563EB"}}' |

Manual initialization

If you cannot use data-site-id on the script tag:

<script src="https://cdn.flowengage.com/flowengage-embed.js" defer></script>
<script>
  window.addEventListener('load', function () {
    window.FlowEngage.init({
      siteId: 'YOUR_SITE_ID',
      widgetSettings: {
        theme: { primaryColor: '#2563EB', position: 'bottom-right' },
        branding: { headerName: 'Support', chatButtonText: 'Chat' },
      },
    });
  });
</script>

CDN API (window.FlowEngage)

| Method | Description | |--------|-------------| | FlowEngage.init({ siteId, widgetSettings?, apiBaseUrl? }) | Mounts the widget. Safe to call after DOMContentLoaded. | | FlowEngage.destroy() | Unmounts the widget and removes injected styles/container. Call before init again if you need to reconfigure. |

To open/close the panel from custom UI inside a React app, use the npm package and useFlowEngage() (openWidget, closeWidget, etc.). The standalone embed exposes init / destroy only.

Optional: customization (npm)

Pass runtime overrides via config on the provider (merged with dashboard defaults):

<FlowEngageProvider
  siteId="YOUR_SITE_ID"
  config={{
    widgetSettings: {
      theme: {
        primaryColor: '#FF5733',
        position: 'bottom-left',
      },
      branding: {
        headerName: 'Cool Support Assistant',
        chatButtonText: 'Talk to us',
      },
    },
  }}
>
  <FlowEngageWidget />
</FlowEngageProvider>

Props

<FlowEngageProvider>

| Prop | Type | Required | Description | |------|------|----------|-------------| | siteId | string | ✅ | Your Site ID from the FlowEngage dashboard | | config | object | ❌ | { widgetSettings?: … } merged with server config |

<FlowEngageWidget>

No props required. It reads state from the nearest FlowEngageProvider.

Using the useFlowEngage Hook

Access the full widget context in any child component:

import { useFlowEngage } from '@flowengage/react-chatbot';

function MyCustomButton() {
  const { openWidget, isOpen, chatHistory } = useFlowEngage();

  return (
    <button type="button" onClick={() => openWidget({ notifyChatInitiated: true })}>
      Chat ({chatHistory.length} messages)
    </button>
  );
}

Available context values

| Value | Type | Description | |-------|------|-------------| | status | "booting" \| "ready" \| "error" | Widget boot status | | isOpen | boolean | Whether the chat panel is open | | chatHistory | Message[] | Full chat history array | | isHumanHandled | boolean | Whether a live agent has taken over | | agentName | string \| null | Active agent's name | | agentHeadshot | string \| null | Active agent's avatar URL | | isAgentTyping | boolean | Agent typing indicator | | isLoading | boolean | Waiting for AI response | | isVoiceMode | boolean | Voice mode active | | isRateLimited | boolean | Rate limit hit | | openWidget() | function | Open the chat panel | | closeWidget() | function | Close the chat panel | | toggleWidget() | function | Toggle the panel | | sendMessage(msg, category?) | function | Send a message | | setVoiceMode(bool) | function | Toggle voice mode | | notifyRouteChange() | function | Notify tracker of SPA route change |

SPA Route Tracking

For client-side routing (React Router, Next.js App Router, etc.):

import { useFlowEngage } from '@flowengage/react-chatbot';
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function RouteTracker() {
  const { notifyRouteChange } = useFlowEngage();
  const location = useLocation();

  useEffect(() => {
    notifyRouteChange();
  }, [location.pathname]);

  return null;
}

How It Works

Your App
   └── <FlowEngageProvider siteId="...">
          │
          ├── Boot:  GET /api/widget/bootstrap  → validates siteId, returns config
          ├── Start: POST /api/ai/chat           → loads chat history
          ├── Chat:  Socket.IO                   → real-time messages & agent handoff
          └── Track: Socket.IO events            → visitor session, page views

Backend URLs are resolved by FlowEngage; you normally do not set them unless using apiBaseUrl (advanced).

Getting Your Site ID

1. Log in to the FlowEngage Dashboard
2. Open Integration Guide or your site / workspace settings
3. Copy the Site ID for your website

License

MIT © FlowEngage