Mona Chat Widget

Embeddable React chat widget for the Mona Chatbot Builder platform, developed by Netmonk's data & solution team. It connects to an Engine webhook and supports guest or authenticated chat, voice input/playback, and light/dark themes.

Install and use

Requires React 18 and React DOM 18 in the host application.

npm install @random-data-team/mona-chat-widget

import { ChatWidget } from "@random-data-team/mona-chat-widget";
import "@random-data-team/mona-chat-widget/dist/style.css";

export default function App() {
  return (
    <ChatWidget
      sourceId="source-123"
      webhookUrl="https://engine.example/chat"
    />
  );
}

sourceId identifies the chat source/channel; webhookUrl is the required Engine webhook endpoint. Omitting userId uses a browser-fingerprint visitor ID for guest chat. A userId alone does not supply an authentication token.

Essential props and authentication

| Prop | Purpose | |---|---| | userId, username | Optional host user ID and session display name. | | authToken, onAuthRequired | Host-managed Engine-compatible token and callback to request login/renewal. The host refreshes the token. | | authUrl, getConnectorToken | Legacy provider mode. Requires a callback returning the connector login's local access_token; initial auth and refresh send it as token_prime. Never return upstream access_token_prime. | | connectorInitUrl, getPrimeToken | Connector init mode: body-free POST with the current host Kong bearer; returned Connector JWT/identity authenticate Engine requests. | | data | Extra ordinary-chat variables as key=value~key2=value2; keep auth/session identity out of this string. | | voiceConfig | Optional STT, TTS and MinIO configuration. | | themeMode, width, height, position | Layout/theme; defaults: "light", "25vw", "90vh", "fixed". | | enabled, showLauncher, autoOpen, onToggle | Availability, launcher and open/close behavior; defaults: true, true, false. |

When configured, Connector init takes precedence over host-token and legacy provider modes; otherwise a non-empty authToken takes precedence over authUrl. Connector init does not fall back to legacy auth on failure. Use the mode supported by your deployment. Tokens for Engine, Connector login and Prime/Kong are distinct; the widget does not accept passwords or OTP values. Keep bearer/API endpoints in trusted host configuration. Detailed examples and the full prop contract are in the integration guide below.

Prime forms: host opt-in

Starting with 2.10.0, the library releases Add Network Device and Add Alert Notification behind the host opt-in and binding gates. Without the required setup, creation remains unavailable and the widget offers Return to chat. Legacy create contracts remain unavailable; /add-network-device and /add-alert go to Engine as ordinary text. Ordinary chat and authentication remain available.

primeFormsEnabled defaults to false. Setting it and supplying connectorInitUrl, connectorAttestUrl, getPrimeToken and primeApiBaseUrl allows the production form integration with PRIME_FORMS_RELEASED = true. Forms also require an Engine v2 envelope whose principal matches the current Connector session, with bearer attestation before each write. Do not treat host flags as server authorization or production approval.

The protected __form_result__ contract sends only status, protocol IDs and the completed resource ID, alongside existing session identity and Engine authentication. Display names, arbitrary host variables and caller display text are excluded; consumers must use the identifiers. Prime/Kong bearers and the Prime base URL are not sent to the Engine webhook. The full binding, recovery, security prerequisites and known limits are in the Prime integration document.

For a local mock preview without Kong or Engine, pass boolean primeFormsPreview={true} on localhost, 127.0.0.1 or [::1]. It defaults off and uses fixture catalogs and mock submissions for both slash commands. See local preview instructions.

Documentation and version history

These repository links also work from the npm README; docs/ is not included in the package tarball. They target develop, which may be ahead of an installed package. For an exact contract, consult the source revision used by your package.

• Consumer integration and full props
• Voice API contracts
• Prime binding, recovery and security requirements
• Prime Review UI and mock harness
• Design
• Changelog

package.json is the current version source of truth. The changelog preserves recorded history.

Local development

npm install
npm run build            # Library and TypeScript declarations in dist/
npm test -- --run        # One Vitest run
npm run storybook        # http://localhost:5177

Use npm run dev for the demo and /prime-forms.html mock harness; npm run build-app builds the demo. npm run build-storybook and npm run serve-storybook build/preview Storybook. Publishing and deployment are owner-managed operations.