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
• Embedded mode (default) or floating button mode
• Customizable theming with light, dark, and system color modes
• Style isolation (won't conflict with host site CSS)
• Native mobile support via WebView
• Voice input support
• Quick action buttons
• Survey/questionnaire support
• Content citations with overlay view

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

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',
    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({
    // API & Auth
    apiEndpoint: 'https://your-api.com',
    token: 'your-auth-token',
    userType: 'patient',             // 'patient' (default) or 'staff'
    assistantId: 'your-assistant-id',

    // Display mode
    floatingMode: true,          // false = embedded (default), true = FAB button
    position: 'bottom-left',     // FAB position (default: 'bottom-right')
    hideExpandButton: true,      // Hide expand/minimize button from header
    showCloseSlot: true,         // Empty placeholder for custom close button

    // Content
    headerTitle: 'Health Support',
    headerSubtitle: 'Online now',
    greeting: 'Hi! How can I help?',
    placeholder: 'Ask me anything...',
    brandingText: 'Powered by MyCompany',
    disclaimerText: 'AI can make mistakes. Verify important information.',
    headerIcon: '/logo.png',
    fabIcon: '/avatar.png',       // Only used in floating mode
    quickActions: ['I need help', 'Book appointment'],

    // Appearance
    colorMode: 'system',  // 'light', 'dark', or 'system' (auto-detect)
    theme: {
      colors: {
        primary: '#ff6600',        // FAB button, links, main accent
        primaryDark: '#cc5200',    // Hover states
        secondary: '#2d3748',      // Header background
        headerText: '#ffffff',     // Header text color
        background: '#ffffff',     // Chat window background
        surface: '#f7fafc',        // Input/card backgrounds
        text: '#2d3748',           // Primary text
        textLight: '#718096',      // Secondary text, timestamps
        userBubble: '#ff6600',     // User message background
        userBubbleText: '#ffffff', // User message text
        botBubble: '#edf2f7',      // Bot message background
        botBubbleText: '#2d3748',  // Bot message text
      },
      fontFamily: 'Inter, system-ui, sans-serif',
      borderRadius: '8px',
      shadow: '0 4px 12px rgba(0, 0, 0, 0.1)',
    },

    // Callbacks
    onOpen: () => console.log('Chat opened'),
    onClose: () => console.log('Chat closed'),
    onMessageSent: (message) => console.log('Sent:', message),
    onMessageReceived: (message) => console.log('Received:', message),
    onQuickAction: (action) => console.log('Quick action:', action),
    onStreamChunk: (chunk) => console.log('Chunk:', chunk),
    onCitationClick: (citation) => console.log('Citation:', citation),
    onNewChat: () => console.log('New chat started'),
    onWidgetReady: (api) => console.log('Widget ready:', api),
  });
</script>

Via npm import

import '@mypatientspace/chatbot-widget';

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

Patient & Staff Integration

The widget supports two user types with separate API routing. Each type uses different backend endpoints for chat, message history, and assistant lookup.

Patient (Default)

Patient mode is the default — no userType needed:

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

API endpoints used:

• POST /api/patient/chat/stream — Send messages
• GET /api/patient/chat/messages — Load history
• GET /api/patient/assistant — Get assistant config

Staff

Staff mode requires userType: 'staff' along with contextPatientId and patientTypeId:

<script>
  ChatbotWidget.init({
    apiEndpoint: 'https://your-api.com',
    token: 'your-auth-token',
    userType: 'staff',
    contextPatientId: 'patient-123',
    patientTypeId: 'type-456'
  });
</script>

API endpoints used:

• POST /api/staff/chat/stream — Send messages (includes contextPatientId in body)
• GET /api/staff/chat/messages — Load history (requires contextPatientId query param)
• GET /api/staff/assistant/{patientTypeId} — Get assistant config

Required Fields by User Type

API Methods

ChatbotWidget.open();         // Open chat window
ChatbotWidget.close();        // Close chat window
ChatbotWidget.toggle();       // Toggle open/close
ChatbotWidget.startNewChat(); // Clear session and start new chat
ChatbotWidget.update(config); // Update widget configuration
ChatbotWidget.destroy();      // Remove widget completely

Embedded Mode

By default, the widget is embedded inside a container element. You can enable floating mode for a FAB button popup.

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',
    containerSelector: '#my-chat'
  });
</script>

Using floatingMode

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

<script>
  ChatbotWidget.init({
    apiEndpoint: 'https://your-api.com',
    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'
                        });
                        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'
                });
                ChatbotWidget.open();
            </script>
        </body>
        </html>
        """

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

iOS (Objective-C)

#import <UIKit/UIKit.h>
#import <WebKit/WebKit.h>

@interface ChatViewController : UIViewController
@property (nonatomic, strong) WKWebView *webView;
@end

@implementation ChatViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
    config.preferences.javaScriptEnabled = YES;

    self.webView = [[WKWebView alloc] initWithFrame:self.view.bounds configuration:config];
    self.webView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
    [self.view addSubview:self.webView];

    NSString *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' });"
        "ChatbotWidget.open();"
        "</script>"
        "</body>"
        "</html>";

    [self.webView loadHTMLString:html baseURL:[NSURL URLWithString:@"https://your-domain.com"]];
}

@end

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'
            });
            ChatbotWidget.open();
        </script>
    </body>
    </html>
  `;

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

Configuration Reference

All Options

Note: Content fields (greeting, headerTitle, placeholder, brandingText, headerIcon, fabIcon, quickActions, disclaimerText) are loaded from the assistant's API configuration by default. Setting them in the widget config overrides the API values.

Callbacks

Available Theme Colors

Default Fallback Values

Content fields are resolved with this priority: Config > Assistant API > Component default

License

MIT