MPS Chatbot Widget

A standalone chatbot widget that third-party websites can embed via a single <script> tag.

Features

• Self-contained React application bundled into a single JS file
• Easy integration with any website
• Floating button mode (default) or embedded mode
• Customizable theming
• Style isolation (won't conflict with host site CSS)
• Native mobile support via WebView

Tech Stack

• React 19 with TypeScript
• Vite (library mode build)
• Emotion (CSS-in-JS for style isolation)
• lucide-react (icons)

Compatibility

Via CDN/Script Tag (Any Project)

When using the UMD bundle via <script> tag, the widget bundles its own React and renders in an isolated container. Your project's React version doesn't matter — this works with any framework (or no framework at all), including:

• Vanilla JavaScript/HTML
• jQuery
• Angular, Vue, Svelte
• Older React versions (14, 15, 16, etc.)

Via npm Import (React 18+ Required)

When importing as an ES module in a React project:

import '@mypatientspace/chatbot-widget';

You need React 18 or higher. The widget uses modern React features (hooks, Context API) that aren't available in older versions.

Installation

Via CDN (Recommended)

unpkg:

<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>

jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>

Via npm

npm install @mypatientspace/chatbot-widget

Development

# Install dependencies
yarn install

# Start dev server (includes demo UI)
yarn dev

# Build for production
yarn build              # Builds both widget and demo
yarn build:widget       # Widget only
yarn build:demo         # Demo only

# Preview production build
yarn preview

Demo Widget

An embeddable demo page with configuration panel and live preview. Useful for testing and showcasing the widget.

Via CDN

<div id="chatbot-demo" style="height: 600px;"></div>
<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-demo.umd.js"></script>
<script>
  ChatbotWidgetDemo.init({
    containerSelector: '#chatbot-demo',
    showJsonEditor: true,
    initialConfig: {
      apiEndpoint: 'https://your-api.com/chat',
      token: 'your-auth-token',
      headerTitle: 'My Healthcare Bot',
      theme: { colors: { primary: '#007bff' } }
    },
    onConfigChange: (config) => console.log('Config:', config)
  });
</script>

Note: The "Use Mock API" toggle is only available in development mode (yarn dev). When embedding the demo in production, you must provide apiEndpoint and token in the initialConfig.

Demo API

ChatbotWidgetDemo.init(config);    // Initialize demo
ChatbotWidgetDemo.destroy();       // Remove demo
ChatbotWidgetDemo.update(config);  // Update configuration

Demo Configuration

Web Integration

Minimal Setup

<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
<script>
  ChatbotWidget.init({
    apiEndpoint: 'https://your-api.com/chat',
    token: 'your-auth-token'
  });
</script>

Full Customization

<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
<script>
  ChatbotWidget.init({
    apiEndpoint: 'https://your-api.com/chat',
    token: 'your-auth-token',
    headerTitle: 'Health Support',
    greeting: 'Hi! How can I help?',
    brandingText: 'Powered by MyCompany',
    headerIcon: '/logo.png',
    fabIcon: '/avatar.png',
    placeholder: 'Ask me anything...',
    position: 'bottom-left',
    quickActions: ['I need help', 'Book appointment'],
    theme: {
      // All color properties are optional - only set what you want to change
      colors: {
        // Main colors
        primary: '#ff6600',        // FAB button, links, main accent
        primaryDark: '#cc5200',    // Hover states
        secondary: '#2d3748',      // Header background
        accent: '#4299e1',         // Secondary accent
        accentLight: '#bee3f8',    // Light accent

        // Status colors
        success: '#48bb78',        // Success states
        info: '#4299e1',           // Info states
        error: '#f56565',          // Error states

        // Background colors
        background: '#ffffff',     // Chat window background
        surface: '#f7fafc',        // Input/card backgrounds

        // Text colors
        text: '#2d3748',           // Primary text
        textLight: '#718096',      // Secondary text, timestamps

        // Message bubbles
        userBubble: '#ff6600',     // User message background
        userBubbleText: '#ffffff', // User message text
        botBubble: '#edf2f7',      // Bot message background
        botBubbleText: '#2d3748',  // Bot message text

        // Borders
        border: '#e2e8f0',         // Border color
        borderLight: '#edf2f7',    // Light border

        // Other
        white: '#ffffff',          // White color
        recording: '#f56565',      // Voice recording indicator
      },

      // Typography and shape
      fontFamily: 'Inter, system-ui, sans-serif',
      borderRadius: '8px',
      shadow: '0 4px 12px rgba(0, 0, 0, 0.1)',
    }
  });
</script>

Via npm import

import '@mypatientspace/chatbot-widget';

ChatbotWidget.init({
  apiEndpoint: 'https://your-api.com/chat'
});

API Methods

ChatbotWidget.open();    // Open chat window
ChatbotWidget.close();   // Close chat window
ChatbotWidget.toggle();  // Toggle open/close
ChatbotWidget.destroy(); // Remove widget completely

Embedded Mode

By default, the widget displays as a floating button that opens a popup. You can also embed the chat directly inside any container on your page.

Using containerSelector

Embed the chat inside an existing element:

<div id="my-chat" style="width: 400px; height: 600px;"></div>

<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
<script>
  ChatbotWidget.init({
    apiEndpoint: 'https://your-api.com/chat',
    containerSelector: '#my-chat'
  });
</script>

Using floatingMode

Enable floating mode with FAB button (classic chatbot style):

<script>
  ChatbotWidget.init({
    apiEndpoint: 'https://your-api.com/chat',
    floatingMode: true
  });
</script>

Comparison

Mobile Integration

Android (Kotlin)

class ChatActivity : AppCompatActivity() {
    private lateinit var webView: WebView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        webView = WebView(this).apply {
            settings.javaScriptEnabled = true
            settings.domStorageEnabled = true
            loadDataWithBaseURL(
                "https://your-domain.com",
                """
                <!DOCTYPE html>
                <html>
                <head>
                    <meta name="viewport" content="width=device-width, initial-scale=1">
                </head>
                <body style="margin:0;padding:0;">
                    <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
                    <script>
                        ChatbotWidget.init({
                            apiEndpoint: 'https://your-api.com/chat'
                        });
                        ChatbotWidget.open();
                    </script>
                </body>
                </html>
                """.trimIndent(),
                "text/html", "UTF-8", null
            )
        }
        setContentView(webView)
    }
}

iOS (Swift)

import UIKit
import WebKit

class ChatViewController: UIViewController {
    var webView: WKWebView!

    override func viewDidLoad() {
        super.viewDidLoad()

        let config = WKWebViewConfiguration()
        config.preferences.javaScriptEnabled = true

        webView = WKWebView(frame: view.bounds, configuration: config)
        webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(webView)

        let html = """
        <!DOCTYPE html>
        <html>
        <head>
            <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
            <style>body { margin: 0; padding: 0; }</style>
        </head>
        <body>
            <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
            <script>
                ChatbotWidget.init({
                    apiEndpoint: 'https://your-api.com/chat'
                });
                ChatbotWidget.open();
            </script>
        </body>
        </html>
        """

        webView.loadHTMLString(html, baseURL: URL(string: "https://your-domain.com"))
    }
}

React Native

import { WebView } from 'react-native-webview';

const ChatScreen = () => {
  const html = `
    <!DOCTYPE html>
    <html>
    <head>
        <meta name="viewport" content="width=device-width, initial-scale=1">
    </head>
    <body style="margin:0;padding:0;">
        <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
        <script>
            ChatbotWidget.init({
                apiEndpoint: 'https://your-api.com/chat'
            });
            ChatbotWidget.open();
        </script>
    </body>
    </html>
  `;

  return (
    <WebView
      source={{ html }}
      javaScriptEnabled={true}
      domStorageEnabled={true}
    />
  );
};

Configuration Reference

All Options

Callbacks

Message Interface

interface Message {
  id: string;
  content: string;
  sender: 'user' | 'bot';
  timestamp: Date;
  status: 'sending' | 'sent' | 'error';
  audioUrl?: string;  // Base64 audio data URL for TTS playback
}

ThemeConfig Interface

interface ThemeConfig {
  colors?: Partial<ThemeColors>;  // Any subset of theme colors
  fontFamily?: string;
  borderRadius?: string;
  shadow?: string;
}

Available Theme Colors

Default Values

License

MIT