@enigmaaico/webchat-widget

v0.4.2

Published

3 days ago

Embeddable chat widget for the Enigma AI platform. Drop-in React component or single script tag with Shadow-DOM-isolated styles, real-time SSE messaging, and rich message types.

0High
0Medium
0Low

asimz

chat widget react sse enigma-ai chatbot live-chat embeddable

@enigmaaico/webchat-widget

Embeddable chat widget for the Enigma AI platform.

Drop-in React component — npm install and render <WebChatWidget />
Single script tag for plain HTML — no build tools required
Shadow-DOM-isolated styles — never conflict with host CSS
Real-time messaging powered by Server-Sent Events
Rich message types — text, images, video, audio, documents, locations, choice buttons
Bilingual — Arabic (RTL) and English, with auto-detection from <html lang>

Quick start — React / Next.js

npm install @enigmaaico/webchat-widget

import { WebChatWidget } from '@enigmaaico/webchat-widget';

export function App() {
  return (
    <WebChatWidget
      config={{
        webId: 'YOUR_WEB_ID',
        organizationId: 'YOUR_ORGANIZATION_ID',
        apiBaseUrl: 'https://api.example.com',
        sseUrl: 'https://sse.example.com',
        theme: {
          primaryColor: '#4A84E0',
          headerColor: '#2D52A8',
          textColor: '#1f2937',
          backgroundColor: '#ffffff',
          fontFamily: 'Inter, sans-serif',
        },
        branding: {
          title: 'Chat with us',
          avatar: 'https://your-cdn.com/logo.png',
          placeholder: 'Ask me anything…',
          showBranding: true,
        },
        locale: 'en',
        welcomeMessages: {
          en: ['Hi there! 👋 How can I help?'],
          ar: ['أهلاً بك! 👋 كيف يمكنني المساعدة؟'],
        },
        suggestedMessages: {
          en: ['Pricing', 'Book a demo'],
          ar: ['الأسعار', 'احجز عرضًا'],
        },
      }}
    />
  );
}

The widget mounts a floating chat button in the bottom-right corner and isolates all its styles inside a Shadow DOM.

Next.js (App Router)

The widget uses window/document/localStorage, so it must run client-side only. Mark the file with 'use client':

// components/chat-widget.tsx
'use client';

import { WebChatWidget } from '@enigmaaico/webchat-widget';

export function ChatWidget() {
  return (
    <WebChatWidget
      config={{
        webId: process.env.NEXT_PUBLIC_ENIGMA_WEB_ID!,
        organizationId: process.env.NEXT_PUBLIC_ENIGMA_ORG_ID!,
        apiBaseUrl: process.env.NEXT_PUBLIC_ENIGMA_API_URL!,
        sseUrl: process.env.NEXT_PUBLIC_ENIGMA_SSE_URL!,
      }}
    />
  );
}

Then drop <ChatWidget /> into your root layout.

Content Security Policy

If your site sets a strict CSP, allow Google Fonts (the widget loads Poppins inside its Shadow DOM):

style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
font-src 'self' data: https://fonts.gstatic.com;
connect-src 'self' <YOUR_API_ORIGIN> <YOUR_SSE_ORIGIN>;

Quick start — Plain HTML / CDN

For static sites with no build step, use the UMD bundle from jsDelivr. Define a single window.EnigmaWidgetConfig object before the script loads — the widget reads everything from it:

<script>
  window.EnigmaWidgetConfig = {
    webId: 'YOUR_WEB_ID',
    organizationId: 'YOUR_ORGANIZATION_ID',
    apiBaseUrl: 'https://api.example.com',
    sseUrl: 'https://sse.example.com',
    theme: {
      primaryColor: '#4A84E0',
      headerColor: '#2D52A8',
      fontFamily: 'Inter, sans-serif',
    },
    branding: {
      title: 'Chat with us',
      avatar: 'https://your-cdn.com/logo.png',
      placeholder: 'Ask me anything…',
    },
    locale: 'en',
    welcomeMessages: {
      en: ['Hi! 👋'],
      ar: ['أهلاً!'],
    },
    suggestedMessages: {
      en: ['Pricing', 'Book a demo'],
      ar: ['الأسعار', 'احجز عرضًا'],
    },
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/@enigmaaico/webchat-widget/dist/widget.umd.js" defer></script>

If you need programmatic control (e.g. open/close from your own UI), instantiate the SDK manually instead:

<script src="https://cdn.jsdelivr.net/npm/@enigmaaico/webchat-widget/dist/widget.umd.js"></script>
<script>
  const widget = new EnigmaWidget({
    webId: 'YOUR_WEB_ID',
    organizationId: 'YOUR_ORGANIZATION_ID',
    apiBaseUrl: 'https://api.example.com',
    sseUrl: 'https://sse.example.com',
    theme: { primaryColor: '#4A84E0', headerColor: '#2D52A8' },
    branding: { title: 'Chat with us', avatar: 'https://your-cdn.com/logo.png' },
  });
</script>

For environments that can't run JavaScript (e.g. CMS embed blocks), the widget will also bootstrap from a placeholder element with the four required data-* attributes — but only the bare minimum, no theming via attributes:

<div
  data-enigma-widget
  data-web-id="YOUR_WEB_ID"
  data-organization-id="YOUR_ORGANIZATION_ID"
  data-api-url="https://api.example.com"
  data-sse-url="https://sse.example.com"
  data-locale="ar"
></div>
<script src="https://cdn.jsdelivr.net/npm/@enigmaaico/webchat-widget/dist/widget.umd.js"></script>

data-locale is optional ("en" or "ar"). Omit it and the widget reads <html lang>, defaulting to English.

Pin a version in production: …/@enigmaaico/[email protected]/dist/widget.umd.js.

Configuration

All customization is supplied through a single config object — the React config prop, the UMD window.EnigmaWidgetConfig global, or the new EnigmaWidget({...}) constructor argument.

Required

| Field | Description | |---|---| | webId | Your web channel ID from the Enigma AI dashboard | | organizationId | Your organization ID from the dashboard | | apiBaseUrl | Platform backend base URL | | sseUrl | Web-bot SSE service URL |

For UMD installs without window.EnigmaWidgetConfig, these four can also be set as data-web-id / data-organization-id / data-api-url / data-sse-url on a [data-enigma-widget] element.

Theme

| Field | Default | |---|---| | theme.primaryColor | #4A84E0 | | theme.headerColor | #2D52A8 | | theme.textColor | #1f2937 | | theme.backgroundColor | #ffffff | | theme.fontFamily | 'Poppins', sans-serif |

Branding

| Field | Default | |---|---| | branding.title | Chat with us (English) / دردش معنا (Arabic) | | branding.avatar | — (falls back to a chat icon) | | branding.placeholder | Type a message... (English) / اكتب رسالة... (Arabic) | | branding.showBranding | true |

branding.avatar accepts an image URL. The widget renders it in the header, in the floating button, and on the empty-state placeholder; if the URL fails to load, it falls back to the default chat icon. Setting branding.title or branding.placeholder overrides the localized defaults.

Localization

| Field | Default | |---|---| | locale | auto-detected from <html lang>, or 'en' |

Set locale: 'ar' (or data-locale="ar") to render the widget in Arabic. The widget switches to RTL layout, swaps the font to Cairo for Arabic glyph coverage, and translates every UI string (header, placeholder, empty state, status messages, "Powered by", etc.). Resolution order: config.locale → data-locale → <html lang> → 'en'.

Messages

| Field | Default | |---|---| | welcomeMessages | { ar: [], en: [] } | | suggestedMessages | { ar: [], en: [] } |

Both fields are objects with ar and en arrays. The widget shows the array matching the resolved locale.
Channel-level welcomeMessages and suggestedMessages configured in the Enigma AI dashboard take priority over the values passed at install time. Theme and branding are always developer-controlled — the dashboard does not override them.

SDK methods (CDN/UMD usage)

const widget = new EnigmaWidget({ ... });

widget.updateConfig({ theme: { primaryColor: '#ff6600' } });
widget.hide();
widget.show();
widget.destroy();

Supported message types

| Type | Description | |---|---| | Text | Plain text with line break support | | Image | Inline image with optional caption | | Video | HTML5 video player | | Audio | HTML5 audio player | | Document | Clickable download link | | Location | OpenStreetMap preview with "Open in Maps" link | | Choices | Interactive reply buttons |

Architecture

┌─────────────────────────────────┐
│         Your Website            │
│                                 │
│  ┌───────────────────────────┐  │
│  │   Shadow DOM (isolated)   │  │
│  │  ┌─────────────────────┐  │  │
│  │  │  Enigma Chat Widget │  │  │
│  │  └─────────────────────┘  │  │
│  └───────────────────────────┘  │
└──────────┬──────────────────────┘
           │
     ┌─────┴──────┐
     │            │
     ▼            ▼
┌─────────┐  ┌──────────┐
│ Backend │  │ Web Bot  │
│  API    │  │  (SSE)   │
└─────────┘  └──────────┘

Backend API (apiBaseUrl) — channel configuration + message persistence
Web Bot (sseUrl) — sends messages and streams real-time responses

Building from source

yarn install
yarn build      # produces dist/index.{mjs,cjs,d.ts} and dist/widget.umd.js via tsup
yarn dev        # standalone test app at http://localhost:3000
yarn typecheck  # tsc --noEmit

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@enigmaaico/webchat-widget

Quick start — React / Next.js

Next.js (App Router)

Content Security Policy

Quick start — Plain HTML / CDN

Configuration

Required

Theme

Branding

Localization

Messages

SDK methods (CDN/UMD usage)

Supported message types

Architecture

Building from source

License