@data-netmonk/mona-chat-widget 2.5.1 → 2.6.1

package/README.md

@@ -1,760 +1,903 @@
-# Mona Chat Widget
-
-Chat widget package developed by Netmonk data & solution team to be imported in Netmonk products
-
----
-
-### Recent Updates & Breaking Changes
-
----
-
-**Latest Version Changes:**
-
-⚠️ **Breaking Changes:**
-1. **Removed `type` and `agentType` props** - These parameters are no longer used and have been removed from all components
-2. **Renamed `botServerUrl` to `webhookUrl`** - For better clarity and consistency
-3. **`webhookUrl` is now required** - Must be provided as a prop
-4. **`authUrl` and `username` are now direct props** - No longer part of `data` prop for better clarity and type safety
-5. **`userId` is now optional** - Widget automatically generates visitor ID for guest users via browser fingerprinting when `userId` is not provided
-
-✨ **New Features:**
-1. **Guest user support** - Users can chat without logging in
-   - Automatic visitor ID generation using browser fingerprinting (FingerprintJS + SHA256)
-   - `auth: false` flag automatically added to API requests for guest users
-   - Persistent sessions across page reloads for anonymous visitors
-2. **Authentication support** - Automatic token management with refresh on 401 errors
-   - Pass `authUrl` as a direct prop
-   - Widget handles token lifecycle automatically
-3. **Enhanced user authentication handling** - Smart detection of authenticated vs guest users
-   - Compares `userId` with visitor ID to determine authentication status
-   - Automatic `auth` flag management in all API requests
-4. **Enhanced data prop** - Support for custom variables passed to backend via `data` prop
-5. **Improved error handling** - Better fallback mechanisms and error messages
-6. **Direct `username` prop** - Pass username as a top-level prop instead of in data string
-
-📝 **Migration Guide:**
-```jsx
-// Old usage (deprecated)
-<ChatWidget 
-  userId="user123"
-  sourceId="source456"
-  type="prime"
-  botServerUrl="https://api.example.com"
-/>
-
-// Previous version (with data prop)
-<ChatWidget 
-  userId="user123"
-  sourceId="source456"
-  webhookUrl="https://api.example.com/webhook"
-  data="authUrl=https://api.example.com/login/chatwidget~username=John"
-/>
-
-// New usage - Authenticated user (current - recommended)
-<ChatWidget 
-  userId="user123"
-  sourceId="source456"
-  webhookUrl="https://api.example.com/webhook"
-  authUrl="https://api.example.com/login/chatwidget"
-  username="John"
-  data="email=john@example.com~phone=+1234567890"
-/>
-
-// New usage - Guest user (without login)
-<ChatWidget 
-  sourceId="source456"
-  webhookUrl="https://api.example.com/webhook"
-  username="Guest"
-/>
-// Widget automatically generates visitor ID and adds auth: false flag
-
-// New usage - Conditional (handles both logged-in and guest users)
-<ChatWidget 
-  userId={currentUser?.id}  // undefined for guests
-  sourceId="source456"
-  webhookUrl="https://api.example.com/webhook"
-  username={currentUser?.name || "Guest"}
-/>
-```
-
----
-
-## 🚅 Quick start
-
-### Prerequisites
-
----
-
-1. Install dependencies
-   ```
-   npm install --legacy-peer-deps
-   ```
-2. Copy .env.example
-   ```
-   cp .env.example .env
-   ```
-3. Populate .env
-4. Enable mock mode (optional)
-   
-   To test the chat widget without a backend server, set `VITE_USE_MOCK_RESPONSES=true` in your `.env` file. The widget will respond to messages like:
-   - "start", "hello", "hi", "halo" - Greeting messages
-   - "help", "bantuan" - Help information
-   - "terima kasih", "thank you" - Acknowledgments
-   - "bye", "goodbye" - Farewell messages
-   - And more! Check `src/components/ChatWidget/utils/helpers.js` for full list
-
----
-
-### Mock Mode (Demo without Backend)
-
----
-
-The chat widget includes a built-in mock mode for testing and demonstrations without requiring a backend server.
-
-**To enable mock mode:**
-1. Set `VITE_USE_MOCK_RESPONSES=true` in your `.env` file
-2. Run the app normally with `npm run dev`
-
-**Mock responses include:**
-- Greetings (hello, hi, halo, start) - with interactive buttons
-- Help commands
-- Device list with clickable buttons (type "devices" or "show devices")
-- Thank you acknowledgments
-- Farewells
-- Time-based greetings (good morning, etc.)
-- And automatically falls back to mock mode if backend fails
-
-**Interactive Buttons Demo:**
-Type these messages to see button responses:
-- "start" - Welcome message with action buttons
-- "show devices" or "devices" - List of devices as clickable buttons
-- Click any button to trigger the next action
-
-**To add custom mock responses:**
-Edit the `mockBotResponses` object in `src/components/ChatWidget/utils/mockBotResponses.js`
-
-For text-only responses:
-```javascript
-"trigger": "Response text"
-```
-
-For responses with buttons:
-```javascript
-"trigger": {
-  text: "Your message here",
-  buttons: [
-    { title: "Button 1", payload: "action_1" },
-    { title: "Button 2", payload: "action_2" },
-    { title: "Link Button", url: "https://example.com" }
-  ]
-}
-```
-
----
-
-### Storybook
-
----
-
-1. **How to run Storybook locally** (access at http://localhost:5177)
-
-   ```
-   npm run storybook
-   ```
-
-2. **How to build Storybook**
-
-   ```
-   npm run build-storybook
-   ```
-
-3. **How to serve Storybook**
-
-   ```
-   npm run serve-storybook
-   ```
-
----
-
-### Library (how to update and publish)
-
----
-
-1. **Commit changes**
-   ```
-   git add .
-   git commit -m "Your commit message"
-   ```
-2. **Update version**
-
-   ```bash
-   npm version patch  # for bug fixes (1.0.0 -> 1.0.1)
-   ```
-
-   ```bash
-   npm version minor  # for new features (1.0.0 -> 1.1.0)
-   ```
-
-   ```bash
-   npm version major  # for breaking changes (1.0.0 -> 2.0.0)
-   ```
-
-3. **Build as a library** (build file at `/dist` directory)
-
-   ```
-   npm run build
-   ```
-
-4. **Copy declaration file to `/dist`**
-
-   ```
-   cp ./src/declarations/index.d.ts ./dist/index.d.ts
-   ```
-
-5. **Publish**
-
-   ```
-   npm publish
-   ```
-
----
-
-### Library (how to import on your project)
-
----
-
-1. **Install package**
-   ```bash
-   npm install @data-netmonk/mona-chat-widget
-   ```
-
-2. **Import styles on your `App.jsx` or `index.jsx`**
-
-   ```jsx
-   import "@data-netmonk/mona-chat-widget/dist/style.css";
-   ```
-
-3. **Import & use component**
-
-   ```jsx
-   import { ChatWidget } from "@data-netmonk/mona-chat-widget";
-
-   function App() {
-     return (
-       <ChatWidget 
-         userId="user123" 
-         sourceId="691e1b5952068ff7aaeccffc9"
-         webhookUrl="https://your-backend-url.com"
-       />
-     );
-   }
-   ```
-
----
-
-### Component Props
-
----
-
-#### Required Props
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `sourceId` | `string` | **Required.** Source/channel identifier for the chat |
-| `webhookUrl` | `string` | **Required.** Backend webhook URL |
-
-#### Optional Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `userId` | `string` | Generated visitor ID | Unique identifier for the user. **Optional** - if not provided, a unique visitor ID is automatically generated using browser fingerprinting for guest users |
-| `authUrl` | `string` | - | Authentication endpoint URL for token-based authentication |
-| `username` | `string` | - | Username for the session (sent to backend in variables) |
-| `data` | `string` | - | Additional custom variables in format `key1=value1~key2=value2` |
-| `width` | `string` | `"25vw"` | Widget width (CSS value) |
-| `height` | `string` | `"90vh"` | Widget height (CSS value) |
-| `right` | `string` | `"1.25rem"` | Distance from right edge |
-| `bottom` | `string` | `"1.25rem"` | Distance from bottom edge |
-| `zIndex` | `number` | `2000` | CSS z-index for widget positioning |
-| `position` | `string` | `"fixed"` | CSS position (`"fixed"` or `"relative"`) |
-| `onToggle` | `function` | - | Callback when widget opens/closes: `(isOpen: boolean) => void` |
-
----
-
-### Guest User Support
-
----
-
-The widget now supports **guest users** (users who haven't logged in or before logging in). When `userId` is not provided, the widget automatically generates a unique visitor ID using browser fingerprinting.
-
-**How it works:**
-
-1. **Browser Fingerprinting**: Uses FingerprintJS to generate a unique identifier based on:
-   - Browser characteristics (user agent, screen resolution, timezone, etc.)
-   - Incognito/private browsing detection
-   - Combined into a SHA256 hash for consistency
-
-2. **Automatic Guest Detection**: The widget automatically detects guest users and:
-   - Generates a visitor ID if `userId` is not provided
-   - Adds `auth: false` flag to all API requests for guest users
-   - Uses the visitor ID as the effective user ID throughout the session
-
-3. **Persistent Sessions**: The visitor ID remains consistent across page reloads (unless browser fingerprint changes or user clears data)
-
-**When to use guest mode:**
-- Public-facing websites where users can chat without logging in
-- Support widgets for anonymous visitors
-- Pre-login customer service interactions
-- Any scenario where user authentication is optional
-
-**When to provide userId:**
-- Users who are logged into your application
-- When you need to track chat history across devices
-- When authentication is required for personalized responses
-- Enterprise or internal applications
-
----
-
-### Usage Examples
-
----
-
-#### Basic Usage (Authenticated User)
-
-```jsx
-import { ChatWidget } from "@data-netmonk/mona-chat-widget";
-import "@data-netmonk/mona-chat-widget/dist/style.css";
-
-function App() {
-  return (
-    <ChatWidget 
-      userId="user123" 
-      sourceId="691e1b5952068ff7aaeccffc9"
-      webhookUrl="https://api.example.com/webhook"
-    />
-  );
-}
-```
-
-#### Guest User (Without Login)
-
-For anonymous visitors or users who haven't logged in:
-
-```jsx
-import { ChatWidget } from "@data-netmonk/mona-chat-widget";
-import "@data-netmonk/mona-chat-widget/dist/style.css";
-
-function App() {
-  return (
-    <ChatWidget 
-      sourceId="691e1b5952068ff7aaeccffc9"
-      webhookUrl="https://api.example.com/webhook"
-    />
-  );
-}
-```
-
-**What happens:**
-- Widget automatically generates a visitor ID using browser fingerprinting
-- All API requests include `auth: false` in variables to indicate guest user
-- No login required - users can start chatting immediately
-
-#### Conditional userId (Logged in or Guest)
-
-Handle both logged-in users and guests dynamically:
-
-```jsx
-import { ChatWidget } from "@data-netmonk/mona-chat-widget";
-import "@data-netmonk/mona-chat-widget/dist/style.css";
-
-function App() {
-  const currentUser = getCurrentUser(); // Your auth function
-  
-  return (
-    <ChatWidget 
-      userId={currentUser?.id}  // Provide userId if logged in, undefined if not
-      sourceId="691e1b5952068ff7aaeccffc9"
-      webhookUrl="https://api.example.com/webhook"
-      username={currentUser?.name}
-    />
-  );
-}
-```
-
-**Behavior:**
-- If `currentUser.id` exists → Uses provided userId (authenticated user)
-- If `currentUser.id` is `null`/`undefined` → Generates visitor ID (guest user)
-- Backend receives `auth: false` flag only for guest users
-
-#### With Custom Variables
-
-Pass custom user data like email, phone number, etc. to the backend:
-
-```jsx
-<ChatWidget 
-  userId="user123"
-  sourceId="691e1b5952068ff7aaeccffc9"
-  webhookUrl="https://api.example.com/webhook"
-  username="John Doe"
-  data="telephone_number=+628123456789~email=john@example.com"
-/>
-```
-
-**Variables sent to backend:**
-```json
-{
-  "chat_id": "...",
-  "session_id": "...",
-  "user_id": "user123",
-  "message": "Hello",
-  "type": "text",
-  "variables": {
-    "username": "John Doe",
-    "telephone_number": "+628123456789",
-    "email": "john@example.com"
-  }
-}
-```
-}
-```
-#### With Authentication (NEW!)
-
-The widget supports automatic authentication with token refresh on expiry:
-
-```jsx
-<ChatWidget 
-  userId="user123"
-  sourceId="691e1b5952068ff7aaeccffc9"
-  webhookUrl="https://api.example.com/webhook"
-  authUrl="https://api.example.com/login/chatwidget"
-  username="John Doe"
-/>
-```
-
-**How authentication works:**
-
-1. **Initial Authentication**: When the widget loads (on Launcher mount), if `authUrl` is provided as a prop, it automatically calls the auth API:
-   ```
-   POST {authUrl}
-   Body: { "user_id": "user123" }
-   Response: { "token": "eyJ..." }
-   ```
-
-2. **Session Initialization**: After getting the token, the widget calls the init endpoint to establish the session:
-   ```
-   POST {webhookUrl}/{sourceId}/init
-   Body: {
-     "session_id": "...",
-     "user_id": "user123",
-     "token": "eyJ...",
-     "username": "John Doe"
-   }
-   ```
-
-3. **Automatic Token Refresh**: If the webhook returns **401 Unauthorized** (token expired/revoked), the widget automatically:
-   - Calls the `authUrl` again to get a fresh token
-   - Re-initializes the session with the new token
-   - Updates the `authToken` in variables
-   - Retries the failed request with the new token
-   - This happens transparently without user interaction
-
-**Combined example with auth and custom variables:**
-```jsx
-<ChatWidget 
-  userId="user123"
-  sourceId="691e1b5952068ff7aaeccffc9"
-  webhookUrl="https://api.example.com/webhook"
-  authUrl="https://api.example.com/login/chatwidget"
-  username="John"
-  data="email=john@example.com~phone=+628123456789"
-/>
-```
-
-**Auth Flag (`auth` variable):**
-The widget automatically adds an `auth: false` flag to the `variables` object when the user is a guest (not authenticated):
-- When `userId === visitorId` (browser fingerprint), the widget adds `auth: false` to variables
-- When `userId !== visitorId` (authenticated user), no `auth` flag is added to variables
-
-**Guest user example** (userId equals browser fingerprint):
-```json
-{
-  "chat_id": "...",
-  "session_id": "...",
-  "user_id": "visitor_abc123",
-  "message": "Hello",
-  "type": "text",
-  "variables": {
-    "username": "Guest",
-    "auth": false
-  }
-}
-```
-
-**Authenticated user example** (userId is different from browser fingerprint):
-```json
-{
-  "chat_id": "...",
-  "session_id": "...",
-  "user_id": "user123",
-  "message": "Hello",
-  "type": "text",
-  "variables": {
-    "username": "John Doe",
-    "email": "john@example.com"
-  }
-}
-```
-
-This `auth: false` flag is automatically added in:
-- Session initialization payload (when guest)
-- All message requests (when guest)
-- Button postback requests (when guest)
-
-**Note:** The `data` prop is for additional custom variables only. Required parameters (`userId`, `sourceId`, `webhookUrl`) and common optional parameters (`authUrl`, `username`) should be passed as direct props for better type safety and clarity.
-
-#### Custom Styling
-
-```jsx
-<ChatWidget 
-  userId="user123"  // Optional
-  sourceId="691e1b5952068ff7aaeccffc9"
-  webhookUrl="https://api.example.com/webhook"
-  width="400px"
-  height="600px"
-  right="20px"
-  bottom="20px"
-  zIndex={9999}
-/>
-```
-
-#### Embedded in Layout (Relative Positioning)
-
-```jsx
-<div style={{ display: 'grid', gridTemplateColumns: '1fr 400px' }}>
-  <div>Main content</div>
-  <ChatWidget 
-    userId="user123"  // Optional
-    sourceId="691e1b5952068ff7aaeccffc9"
-    webhookUrl="https://api.example.com/webhook"
-    position="relative"
-    width="100%"
-    height="100vh"
-  />
-</div>
-```
-
-#### With Toggle Callback
-
-```jsx
-function App() {
-  const handleToggle = (isOpen) => {
-    console.log('Chat widget is', isOpen ? 'open' : 'closed');
-    // Track analytics, update UI, etc.
-  };
-
-  return (
-    <ChatWidget 
-      userId="user123"  // Optional
-      sourceId="691e1b5952068ff7aaeccffc9"
-      webhookUrl="https://api.example.com/webhook"
-      onToggle={handleToggle}
-    />
-  );
-}
-```
-
-#### Full-Screen Widget
-
-```jsx
-<ChatWidget 
-  userId="user123"  // Optional - supports guest users
-  sourceId="691e1b5952068ff7aaeccffc9"
-  webhookUrl="https://api.example.com/webhook"
-  width="100vw"
-  height="100vh"
-  right="0"
-  bottom="0"
-/>
-```
-
----
-
-### Data Prop Format & Helper Function
-
----
-
-The `data` prop allows you to pass additional custom variables via a single string. This is especially useful when you need to dynamically pass user-specific data or pass it through URL parameters.
-
-**Format:** `key=value` pairs separated by `~`
-
-**Example data string:**
-```
-email=john@example.com~phone=+1234567890~department=Engineering
-```
-
-**Note:** `authUrl` and `username` are now **direct props** and should not be included in the `data` string.
-
-#### Building Data String Programmatically
-
-Instead of manually constructing the data string, you can create a helper function to build it dynamically. This approach is recommended for production applications as it:
-- Prevents syntax errors in the data string format
-- Makes the code more maintainable and readable
-- Allows for conditional inclusion of parameters
-- Handles URL encoding automatically if needed
-
-**Create a helper function** (`src/helpers/chatWidget.js` or similar):
-
-```jsx
-/**
- * Builds the data string for ChatWidget component
- * @param {Object} params - Object containing all parameters
- * @param {string} params.email - Optional: User's email address
- * @param {string} params.phone - Optional: User's phone number
- * @param {Object} params.customFields - Optional: Any additional custom fields as key-value pairs
- * @returns {string} Formatted data string for ChatWidget (always returns a string)
- * 
- * @example
- * // Returns: "email=john@example.com~phone=+1234567890~department=Engineering"
- * buildChatWidgetData({
- *   email: "john@example.com",
- *   phone: "+1234567890",
- *   customFields: { department: "Engineering" }
- * });
- */
-export const buildChatWidgetData = ({ 
-  email, 
-  phone,
-  customFields = {} 
-}) => {
-  const parts = [];
-  
-  // Add standard fields
-  if (email) {
-    parts.push(`email=${encodeURIComponent(email)}`);
-  }
-  
-  if (phone) {
-    parts.push(`phone=${encodeURIComponent(phone)}`);
-  }
-  
-  // Add any custom fields dynamically
-  // Note: customFields is just a convenience parameter for the helper function
-  // Each field will be flattened into the string format: key=value~key2=value2
-  Object.entries(customFields).forEach(([key, value]) => {
-    if (value) {
-      parts.push(`${key}=${encodeURIComponent(String(value))}`);
-    }
-  });
-  
-  // Returns a string like: "email=john@example.com~phone=+1234567890~department=Engineering"
-  return parts.join("~");
-};
-```
-
-**Important:** The `customFields` parameter is **NOT** passed as an object to the widget. It's just a convenient way to pass multiple additional fields to the helper function. The function flattens everything into a single string format.
-
-**Usage in your application:**
-
-```jsx
-import { ChatWidget } from "@data-netmonk/mona-chat-widget";
-import "@data-netmonk/mona-chat-widget/dist/style.css";
-import { buildChatWidgetData } from "./helpers/chatWidget";
-
-function App() {
-  // Get user data from your auth system, state, or props
-  const user = {
-    id: "user123",
-    name: "John Doe",
-    email: "john@example.com",
-    phone: "+628123456789"
-  };
-  
-  // Build the data string with custom variables only
-  const customData = buildChatWidgetData({
-    email: user.email,
-    phone: user.phone,
-    customFields: {
-      department: "Engineering",
-      role: "Developer",
-      company: "Acme Corp"
-    }
-  });
-  
-  // customData is now a STRING like:
-  // "email=john@example.com~phone=%2B628123456789~department=Engineering~role=Developer~company=Acme%20Corp"
-
-  return (
-    <ChatWidget 
-      userId={user.id}
-      sourceId="691e1b5952068ff7aaeccffc9"
-      webhookUrl="https://api.example.com/webhook"
-      authUrl="https://api.example.com/login/chatwidget"  // Direct prop
-      username={user.name}  // Direct prop
-      data={customData}  // Only additional variables
-    />
-  );
-}
-```
-
-**With conditional authentication:**
-
-```jsx
-function App() {
-  const authUrl = import.meta.env.VITE_CHAT_AUTH_ENABLED === "true" 
-    ? import.meta.env.VITE_CHAT_AUTH_URL 
-    : null;
-  
-  const customData = buildChatWidgetData({
-    email: getCurrentUser().email,
-    customFields: {
-      department: "Sales"
-    }
-  });
-
-  return (
-    <ChatWidget 
-      userId={getCurrentUser().id}
-      sourceId="691e1b5952068ff7aaeccffc9"
-      webhookUrl={import.meta.env.VITE_WEBHOOK_URL}
-      authUrl={authUrl}  // Direct prop (conditionally set)
-      username={getCurrentUser().name}  // Direct prop
-      data={customData}  // Only additional variables
-    />
-  );
-}
-```
-
-**The helper function handles:**
-- ✅ Proper formatting with `~` separators
-- ✅ URL encoding for special characters
-- ✅ Conditional parameter inclusion (only adds if value exists)
-- ✅ Support for dynamic custom fields
-- ✅ Type safety and documentation via JSDoc comments
-
-### Standalone app (for demonstration)
-
-1. **How to run locally** (access at `http://localhost:${PORT}/${APP_PREFIX}`)
-
-   ```
-   npm run dev
-   ```
-
-2. **How to build as a standalone app** (build file at `/dist-app` directory)
-
-   ```
-   npm run build-app
-   ```
-
-3. **How to serve standalone app** (access at `http://localhost:${PORT}/${APP_PREFIX}`)
-
-   ```
-   npm run serve
-   ```
-
-4. **How to run on docker** (access at `http://localhost:${PORT}/${APP_PREFIX}`)
-
-   ```
-   docker-compose up --build
-   ```
-
----
+# Mona Chat Widget
+
+Chat widget package developed by Netmonk data & solution team to be imported in Netmonk products
+
+---
+
+### Recent Updates & Breaking Changes
+
+---
+
+**Latest Version Changes (`v2.6.1`):**
+
+✅ **Non-breaking Changes:**
+1. **Built-in voice mode button** - Chat widget now includes a microphone button to toggle voice mode directly from the input area
+2. **Speech-to-text flow for voice mode** - Recorded user audio is sent to the configured `VITE_STT_ENDPOINT`, then the transcription is forwarded as a normal chat message
+3. **Phoneme-driven avatar animation** - The widget can animate Mona's avatar during TTS playback based on phoneme/viseme IDs returned by the backend
+4. **Supported phoneme IDs** - `A`, `BP`, `ChJ`, `E`, `FV`, `I`, `KG`, `L`, `M`, `O`, `SZ`, `U`
+
+⚠️ **Previous Breaking Changes:**
+1. **Removed `type` and `agentType` props** - These parameters are no longer used and have been removed from all components
+2. **Renamed `botServerUrl` to `webhookUrl`** - For better clarity and consistency
+3. **`webhookUrl` is now required** - Must be provided as a prop
+4. **`authUrl` and `username` are now direct props** - No longer part of `data` prop for better clarity and type safety
+5. **`userId` is now optional** - Widget automatically generates visitor ID for guest users via browser fingerprinting when `userId` is not provided
+
+✨ **New Features:**
+1. **Guest user support** - Users can chat without logging in
+   - Automatic visitor ID generation using browser fingerprinting (FingerprintJS + SHA256)
+   - `auth: false` flag automatically added to API requests for guest users
+   - Persistent sessions across page reloads for anonymous visitors
+2. **Authentication support** - Automatic token management with refresh on 401 errors
+   - Pass `authUrl` as a direct prop
+   - Widget handles token lifecycle automatically
+3. **Enhanced user authentication handling** - Smart detection of authenticated vs guest users
+   - Compares `userId` with visitor ID to determine authentication status
+   - Automatic `auth` flag management in all API requests
+4. **Enhanced data prop** - Support for custom variables passed to backend via `data` prop
+5. **Improved error handling** - Better fallback mechanisms and error messages
+6. **Direct `username` prop** - Pass username as a top-level prop instead of in data string
+
+📝 **Migration Guide:**
+```jsx
+// Old usage (deprecated)
+<ChatWidget 
+  userId="user123"
+  sourceId="source456"
+  type="prime"
+  botServerUrl="https://api.example.com"
+/>
+
+// Previous version (with data prop)
+<ChatWidget 
+  userId="user123"
+  sourceId="source456"
+  webhookUrl="https://api.example.com/webhook"
+  data="authUrl=https://api.example.com/login/chatwidget~username=John"
+/>
+
+// New usage - Authenticated user (current - recommended)
+<ChatWidget 
+  userId="user123"
+  sourceId="source456"
+  webhookUrl="https://api.example.com/webhook"
+  authUrl="https://api.example.com/login/chatwidget"
+  username="John"
+  data="email=john@example.com~phone=+1234567890"
+/>
+
+// New usage - Guest user (without login)
+<ChatWidget 
+  sourceId="source456"
+  webhookUrl="https://api.example.com/webhook"
+  username="Guest"
+/>
+// Widget automatically generates visitor ID and adds auth: false flag
+
+// New usage - Conditional (handles both logged-in and guest users)
+<ChatWidget 
+  userId={currentUser?.id}  // undefined for guests
+  sourceId="source456"
+  webhookUrl="https://api.example.com/webhook"
+  username={currentUser?.name || "Guest"}
+/>
+```
+
+---
+
+## 🚅 Quick start
+
+### Prerequisites
+
+---
+
+1. Install dependencies
+   ```
+   npm install --legacy-peer-deps
+   ```
+2. Copy .env.example
+   ```
+   cp .env.example .env
+   ```
+3. Populate .env
+4. Optional speech endpoints
+
+  To enable voice mode and phoneme-based avatar animation, set these environment variables in your `.env` file:
+  ```
+  VITE_STT_ENDPOINT=https://voice.netmonk-ai.tech/stt
+  VITE_STT_API_KEY=
+  VITE_STT_API_KEY_HEADER=x-api-key
+  VITE_STT_API_KEY_PREFIX=
+  VITE_TTS_ENDPOINT=https://your-tts-service.example.com/synthesize
+  VITE_TTS_API_KEY=
+  VITE_TTS_API_KEY_HEADER=Authorization
+  VITE_TTS_API_KEY_PREFIX=Bearer
+  VITE_PREFER_WEBHOOK_TTS=true
+  VITE_TTS_MINIO_OBJECT_ENDPOINT=http://localhost:8000/minio/object
+  VITE_TTS_MINIO_API_KEY=
+  VITE_TTS_MINIO_API_KEY_HEADER=X-API-Key
+  VITE_TTS_MINIO_API_KEY_PREFIX=
+  VITE_TTS_MINIO_BUCKET=chatbot-tts
+  VITE_TTS_MINIO_DOWNLOAD=false
+  ```
+
+  `VITE_STT_ENDPOINT` is used by the built-in mic button to transcribe recorded audio.
+  For the Netmonk STT service, set `VITE_STT_API_KEY_HEADER=x-api-key` and leave `VITE_STT_API_KEY_PREFIX` empty so the widget sends the raw key value without `Bearer`.
+  `VITE_PREFER_WEBHOOK_TTS=true` makes the widget prioritize TTS assets from webhook response (for example `tts_assets.items[].audio_object_key`) and use `VITE_TTS_ENDPOINT` only as fallback.
+  Widget tidak lagi konek langsung ke MinIO. Object diambil lewat endpoint voice-engine:
+  `GET /minio/object?object_key=<key>&bucket=<bucket>&download=<true|false>`.
+  `VITE_TTS_MINIO_API_KEY` opsional. Jika diisi, widget mengirim header `X-API-Key` (atau header custom via `VITE_TTS_MINIO_API_KEY_HEADER`).
+  `VITE_TTS_MINIO_BUCKET` dipakai sebagai default bucket bila payload webhook tidak mengirim bucket.
+  Set `VITE_TTS_MINIO_DOWNLOAD=true` jika ingin force download mode saat fetch object.
+  `VITE_TTS_ENDPOINT` is used for fallback TTS playback.
+  The widget expects the TTS response body to contain raw audio binary such as `audio/wav`, and reads lip-sync metadata from `x-tts-visemes-b64`, `x-tts-phonemes-b64`, and `x-tts-phoneme-timeline-b64` response headers.
+  If your TTS endpoint is called cross-origin, the server must expose those headers with `Access-Control-Expose-Headers`.
+  If your TTS service uses a different header such as `x-api-key`, set `VITE_TTS_API_KEY_HEADER=x-api-key` and leave the prefix empty.
+5. Optional TTS debug logging
+   
+  To inspect TTS queue and playback lifecycle in browser console, set `VITE_DEBUG_TTS=true` in your `.env` file.
+  Keep this disabled in production to avoid noisy logs.
+6. Enable mock mode (optional)
+   
+   To test the chat widget without a backend server, set `VITE_USE_MOCK_RESPONSES=true` in your `.env` file. The widget will respond to messages like:
+   - "start", "hello", "hi", "halo" - Greeting messages
+   - "help", "bantuan" - Help information
+   - "terima kasih", "thank you" - Acknowledgments
+   - "bye", "goodbye" - Farewell messages
+   - And more! Check `src/components/ChatWidget/utils/helpers.js` for full list
+
+---
+
+### Mock Mode (Demo without Backend)
+
+---
+
+The chat widget includes a built-in mock mode for testing and demonstrations without requiring a backend server.
+
+**To enable mock mode:**
+1. Set `VITE_USE_MOCK_RESPONSES=true` in your `.env` file
+2. Run the app normally with `npm run dev`
+
+**Mock responses include:**
+- Greetings (hello, hi, halo, start) - with interactive buttons
+- Help commands
+- Device list with clickable buttons (type "devices" or "show devices")
+- Thank you acknowledgments
+- Farewells
+- Time-based greetings (good morning, etc.)
+- And automatically falls back to mock mode if backend fails
+
+**Interactive Buttons Demo:**
+Type these messages to see button responses:
+- "start" - Welcome message with action buttons
+- "show devices" or "devices" - List of devices as clickable buttons
+- Click any button to trigger the next action
+
+**To add custom mock responses:**
+Edit the `mockBotResponses` object in `src/components/ChatWidget/utils/mockBotResponses.js`
+
+For text-only responses:
+```javascript
+"trigger": "Response text"
+```
+
+For responses with buttons:
+```javascript
+"trigger": {
+  text: "Your message here",
+  buttons: [
+    { title: "Button 1", payload: "action_1" },
+    { title: "Button 2", payload: "action_2" },
+    { title: "Link Button", url: "https://example.com" }
+  ]
+}
+```
+
+---
+
+### Storybook
+
+---
+
+1. **How to run Storybook locally** (access at http://localhost:5177)
+
+   ```
+   npm run storybook
+   ```
+
+2. **How to build Storybook**
+
+   ```
+   npm run build-storybook
+   ```
+
+3. **How to serve Storybook**
+
+   ```
+   npm run serve-storybook
+   ```
+
+---
+
+### Library (how to update and publish)
+
+---
+
+1. **Commit changes**
+   ```
+   git add .
+   git commit -m "Your commit message"
+   ```
+2. **Update version**
+
+   ```bash
+   npm version patch  # for bug fixes (1.0.0 -> 1.0.1)
+   ```
+
+   ```bash
+   npm version minor  # for new features (1.0.0 -> 1.1.0)
+   ```
+
+   ```bash
+   npm version major  # for breaking changes (1.0.0 -> 2.0.0)
+   ```
+
+3. **Build as a library** (build file at `/dist` directory)
+
+   ```
+   npm run build
+   ```
+
+4. **Copy declaration file to `/dist`**
+
+   ```
+   cp ./src/declarations/index.d.ts ./dist/index.d.ts
+   ```
+
+5. **Publish**
+
+   ```
+   npm publish
+   ```
+
+---
+
+### Library (how to import on your project)
+
+---
+
+1. **Install package**
+   ```bash
+   npm install @data-netmonk/mona-chat-widget
+   ```
+
+2. **Import styles on your `App.jsx` or `index.jsx`**
+
+   ```jsx
+   import "@data-netmonk/mona-chat-widget/dist/style.css";
+   ```
+
+3. **Import & use component**
+
+   ```jsx
+   import { ChatWidget } from "@data-netmonk/mona-chat-widget";
+
+   function App() {
+     return (
+       <ChatWidget 
+         userId="user123" 
+         sourceId="691e1b5952068ff7aaeccffc9"
+         webhookUrl="https://your-backend-url.com"
+       />
+     );
+   }
+   ```
+
+---
+
+### Component Props
+
+---
+
+#### Required Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `sourceId` | `string` | **Required.** Source/channel identifier for the chat |
+| `webhookUrl` | `string` | **Required.** Backend webhook URL |
+
+#### Optional Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `userId` | `string` | Generated visitor ID | Unique identifier for the user. **Optional** - if not provided, a unique visitor ID is automatically generated using browser fingerprinting for guest users |
+| `authUrl` | `string` | - | Authentication endpoint URL for token-based authentication |
+| `username` | `string` | - | Username for the session (sent to backend in variables) |
+| `data` | `string` | - | Additional custom variables in format `key1=value1~key2=value2` |
+| `width` | `string` | `"25vw"` | Widget width (CSS value) |
+| `height` | `string` | `"90vh"` | Widget height (CSS value) |
+| `right` | `string` | `"1.25rem"` | Distance from right edge |
+| `bottom` | `string` | `"1.25rem"` | Distance from bottom edge |
+| `zIndex` | `number` | `2000` | CSS z-index for widget positioning |
+| `position` | `string` | `"fixed"` | CSS position (`"fixed"` or `"relative"`) |
+| `onToggle` | `function` | - | Callback when widget opens/closes: `(isOpen: boolean) => void` |
+
+---
+
+### Voice Mode & Phoneme Support
+
+---
+
+The widget now includes a built-in microphone button in the input area. Clicking the button toggles voice mode, requests microphone access, records speech, sends the recorded audio to `VITE_STT_ENDPOINT`, and forwards the returned transcription as a regular user message.
+
+If `VITE_STT_API_KEY` is set, the STT request also includes the configured auth header. For `https://voice.netmonk-ai.tech/stt`, use `x-api-key` without any prefix. Other providers can still use `Authorization: Bearer <key>` or any custom header via `.env`.
+
+**Expected STT request/response shape:**
+
+- Request body: `multipart/form-data`
+- Audio field name: `audio`
+- Request headers: `Accept: application/json`, plus `x-api-key: <key>` when configured for the Netmonk STT service
+- Expected JSON response:
+
+```json
+{
+  "text": "Halo, saya mau tanya status tiket saya"
+}
+```
+
+During TTS playback, the header avatar can switch between phoneme images using the metadata returned by the TTS service. The widget currently supports these phoneme IDs:
+
+- `A`
+- `BP`
+- `ChJ`
+- `E`
+- `FV`
+- `I`
+- `KG`
+- `L`
+- `M`
+- `O`
+- `SZ`
+- `U`
+
+Phoneme IDs are normalized case-insensitively in the widget, so values such as `ChJ` and `CHJ` resolve to the same avatar image.
+
+**Preferred webhook TTS asset shape (MinIO-first):**
+
+```json
+{
+  "messages": [{ "type": "text", "text": "Halo, ada yang bisa saya bantu?" }],
+  "tts_assets": {
+    "items": [
+      {
+        "bucket": "chatbot-tts",
+        "response_index": 1,
+        "audio_object_key": "tts/...wav",
+        "phoneme_object_key": "tts/...phonemes.txt",
+        "phoneme_timeline_object_key": "tts/...phoneme-timeline.json",
+        "viseme_timeline_object_key": "tts/...viseme-timeline.json"
+      }
+    ]
+  }
+}
+```
+
+When this payload is available, the widget resolves MinIO object keys first for audio and timeline metadata. If no usable asset is found, it falls back to `VITE_TTS_ENDPOINT`.
+
+**Expected TTS response shape:**
+
+```text
+body: <raw WAV or other audio binary>
+content-type: audio/wav
+x-tts-visemes-b64: W3siaWQiOiJNIiwic3RhcnRNcyI6MCwiZW5kTXMiOjEyMH1d
+x-tts-phonemes-b64: TSBBCg==
+x-tts-phoneme-timeline-b64: W3sicGhvbmVtZSI6Ik0iLCJzdGFydE1zIjowLCJlbmRNcyI6MTIwfV0=
+```
+
+`x-tts-phonemes-b64` is the legacy phoneme string, while `x-tts-phoneme-timeline-b64` is the timed phoneme timeline. The base64 headers should decode as:
+
+Decoded `x-tts-phonemes-b64`:
+
+```text
+M A
+```
+
+Decoded `x-tts-phoneme-timeline-b64`:
+
+```json
+[
+  { "phoneme": "M", "startMs": 0, "endMs": 120 }
+]
+```
+
+Decoded `x-tts-visemes-b64`:
+
+```json
+[
+  { "id": "M", "startMs": 0, "endMs": 120 },
+  { "id": "A", "startMs": 121, "endMs": 260 },
+  { "id": "SZ", "startMs": 261, "endMs": 420 }
+]
+```
+
+The widget still supports the older JSON body format as a fallback, but header-based metadata is now the preferred format for binary audio responses.
+
+---
+
+### Guest User Support
+
+---
+
+The widget now supports **guest users** (users who haven't logged in or before logging in). When `userId` is not provided, the widget automatically generates a unique visitor ID using browser fingerprinting.
+
+**How it works:**
+
+1. **Browser Fingerprinting**: Uses FingerprintJS to generate a unique identifier based on:
+   - Browser characteristics (user agent, screen resolution, timezone, etc.)
+   - Incognito/private browsing detection
+   - Combined into a SHA256 hash for consistency
+
+2. **Automatic Guest Detection**: The widget automatically detects guest users and:
+   - Generates a visitor ID if `userId` is not provided
+   - Adds `auth: false` flag to all API requests for guest users
+   - Uses the visitor ID as the effective user ID throughout the session
+
+3. **Persistent Sessions**: The visitor ID remains consistent across page reloads (unless browser fingerprint changes or user clears data)
+
+**When to use guest mode:**
+- Public-facing websites where users can chat without logging in
+- Support widgets for anonymous visitors
+- Pre-login customer service interactions
+- Any scenario where user authentication is optional
+
+**When to provide userId:**
+- Users who are logged into your application
+- When you need to track chat history across devices
+- When authentication is required for personalized responses
+- Enterprise or internal applications
+
+---
+
+### Usage Examples
+
+---
+
+#### Basic Usage (Authenticated User)
+
+```jsx
+import { ChatWidget } from "@data-netmonk/mona-chat-widget";
+import "@data-netmonk/mona-chat-widget/dist/style.css";
+
+function App() {
+  return (
+    <ChatWidget 
+      userId="user123" 
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
+    />
+  );
+}
+```
+
+#### Guest User (Without Login)
+
+For anonymous visitors or users who haven't logged in:
+
+```jsx
+import { ChatWidget } from "@data-netmonk/mona-chat-widget";
+import "@data-netmonk/mona-chat-widget/dist/style.css";
+
+function App() {
+  return (
+    <ChatWidget 
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
+    />
+  );
+}
+```
+
+**What happens:**
+- Widget automatically generates a visitor ID using browser fingerprinting
+- All API requests include `auth: false` in variables to indicate guest user
+- No login required - users can start chatting immediately
+
+#### Conditional userId (Logged in or Guest)
+
+Handle both logged-in users and guests dynamically:
+
+```jsx
+import { ChatWidget } from "@data-netmonk/mona-chat-widget";
+import "@data-netmonk/mona-chat-widget/dist/style.css";
+
+function App() {
+  const currentUser = getCurrentUser(); // Your auth function
+  
+  return (
+    <ChatWidget 
+      userId={currentUser?.id}  // Provide userId if logged in, undefined if not
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
+      username={currentUser?.name}
+    />
+  );
+}
+```
+
+**Behavior:**
+- If `currentUser.id` exists → Uses provided userId (authenticated user)
+- If `currentUser.id` is `null`/`undefined` → Generates visitor ID (guest user)
+- Backend receives `auth: false` flag only for guest users
+
+#### With Custom Variables
+
+Pass custom user data like email, phone number, etc. to the backend:
+
+```jsx
+<ChatWidget 
+  userId="user123"
+  sourceId="691e1b5952068ff7aaeccffc9"
+  webhookUrl="https://api.example.com/webhook"
+  username="John Doe"
+  data="telephone_number=+628123456789~email=john@example.com"
+/>
+```
+
+**Variables sent to backend:**
+```json
+{
+  "chat_id": "...",
+  "session_id": "...",
+  "user_id": "user123",
+  "message": "Hello",
+  "type": "text",
+  "variables": {
+    "username": "John Doe",
+    "telephone_number": "+628123456789",
+    "email": "john@example.com"
+  }
+}
+```
+}
+```
+#### With Authentication (NEW!)
+
+The widget supports automatic authentication with token refresh on expiry:
+
+```jsx
+<ChatWidget 
+  userId="user123"
+  sourceId="691e1b5952068ff7aaeccffc9"
+  webhookUrl="https://api.example.com/webhook"
+  authUrl="https://api.example.com/login/chatwidget"
+  username="John Doe"
+/>
+```
+
+**How authentication works:**
+
+1. **Initial Authentication**: When the widget loads (on Launcher mount), if `authUrl` is provided as a prop, it automatically calls the auth API:
+   ```
+   POST {authUrl}
+   Body: { "user_id": "user123" }
+   Response: { "token": "eyJ..." }
+   ```
+
+2. **Session Initialization**: After getting the token, the widget calls the init endpoint to establish the session:
+   ```
+   POST {webhookUrl}/{sourceId}/init
+   Body: {
+     "session_id": "...",
+     "user_id": "user123",
+     "token": "eyJ...",
+     "username": "John Doe"
+   }
+   ```
+
+3. **Automatic Token Refresh**: If the webhook returns **401 Unauthorized** (token expired/revoked), the widget automatically:
+   - Calls the `authUrl` again to get a fresh token
+   - Re-initializes the session with the new token
+   - Updates the `authToken` in variables
+   - Retries the failed request with the new token
+   - This happens transparently without user interaction
+
+**Combined example with auth and custom variables:**
+```jsx
+<ChatWidget 
+  userId="user123"
+  sourceId="691e1b5952068ff7aaeccffc9"
+  webhookUrl="https://api.example.com/webhook"
+  authUrl="https://api.example.com/login/chatwidget"
+  username="John"
+  data="email=john@example.com~phone=+628123456789"
+/>
+```
+
+**Auth Flag (`auth` variable):**
+The widget automatically adds an `auth: false` flag to the `variables` object when the user is a guest (not authenticated):
+- When `userId === visitorId` (browser fingerprint), the widget adds `auth: false` to variables
+- When `userId !== visitorId` (authenticated user), no `auth` flag is added to variables
+
+**Guest user example** (userId equals browser fingerprint):
+```json
+{
+  "chat_id": "...",
+  "session_id": "...",
+  "user_id": "visitor_abc123",
+  "message": "Hello",
+  "type": "text",
+  "variables": {
+    "username": "Guest",
+    "auth": false
+  }
+}
+```
+
+**Authenticated user example** (userId is different from browser fingerprint):
+```json
+{
+  "chat_id": "...",
+  "session_id": "...",
+  "user_id": "user123",
+  "message": "Hello",
+  "type": "text",
+  "variables": {
+    "username": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+
+This `auth: false` flag is automatically added in:
+- Session initialization payload (when guest)
+- All message requests (when guest)
+- Button postback requests (when guest)
+
+**Note:** The `data` prop is for additional custom variables only. Required parameters (`userId`, `sourceId`, `webhookUrl`) and common optional parameters (`authUrl`, `username`) should be passed as direct props for better type safety and clarity.
+
+#### Custom Styling
+
+```jsx
+<ChatWidget 
+  userId="user123"  // Optional
+  sourceId="691e1b5952068ff7aaeccffc9"
+  webhookUrl="https://api.example.com/webhook"
+  width="400px"
+  height="600px"
+  right="20px"
+  bottom="20px"
+  zIndex={9999}
+/>
+```
+
+#### Embedded in Layout (Relative Positioning)
+
+```jsx
+<div style={{ display: 'grid', gridTemplateColumns: '1fr 400px' }}>
+  <div>Main content</div>
+  <ChatWidget 
+    userId="user123"  // Optional
+    sourceId="691e1b5952068ff7aaeccffc9"
+    webhookUrl="https://api.example.com/webhook"
+    position="relative"
+    width="100%"
+    height="100vh"
+  />
+</div>
+```
+
+#### With Toggle Callback
+
+```jsx
+function App() {
+  const handleToggle = (isOpen) => {
+    console.log('Chat widget is', isOpen ? 'open' : 'closed');
+    // Track analytics, update UI, etc.
+  };
+
+  return (
+    <ChatWidget 
+      userId="user123"  // Optional
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
+      onToggle={handleToggle}
+    />
+  );
+}
+```
+
+#### Full-Screen Widget
+
+```jsx
+<ChatWidget 
+  userId="user123"  // Optional - supports guest users
+  sourceId="691e1b5952068ff7aaeccffc9"
+  webhookUrl="https://api.example.com/webhook"
+  width="100vw"
+  height="100vh"
+  right="0"
+  bottom="0"
+/>
+```
+
+---
+
+### Data Prop Format & Helper Function
+
+---
+
+The `data` prop allows you to pass additional custom variables via a single string. This is especially useful when you need to dynamically pass user-specific data or pass it through URL parameters.
+
+**Format:** `key=value` pairs separated by `~`
+
+**Example data string:**
+```
+email=john@example.com~phone=+1234567890~department=Engineering
+```
+
+**Note:** `authUrl` and `username` are now **direct props** and should not be included in the `data` string.
+
+#### Building Data String Programmatically
+
+Instead of manually constructing the data string, you can create a helper function to build it dynamically. This approach is recommended for production applications as it:
+- Prevents syntax errors in the data string format
+- Makes the code more maintainable and readable
+- Allows for conditional inclusion of parameters
+- Handles URL encoding automatically if needed
+
+**Create a helper function** (`src/helpers/chatWidget.js` or similar):
+
+```jsx
+/**
+ * Builds the data string for ChatWidget component
+ * @param {Object} params - Object containing all parameters
+ * @param {string} params.email - Optional: User's email address
+ * @param {string} params.phone - Optional: User's phone number
+ * @param {Object} params.customFields - Optional: Any additional custom fields as key-value pairs
+ * @returns {string} Formatted data string for ChatWidget (always returns a string)
+ * 
+ * @example
+ * // Returns: "email=john@example.com~phone=+1234567890~department=Engineering"
+ * buildChatWidgetData({
+ *   email: "john@example.com",
+ *   phone: "+1234567890",
+ *   customFields: { department: "Engineering" }
+ * });
+ */
+export const buildChatWidgetData = ({ 
+  email, 
+  phone,
+  customFields = {} 
+}) => {
+  const parts = [];
+  
+  // Add standard fields
+  if (email) {
+    parts.push(`email=${encodeURIComponent(email)}`);
+  }
+  
+  if (phone) {
+    parts.push(`phone=${encodeURIComponent(phone)}`);
+  }
+  
+  // Add any custom fields dynamically
+  // Note: customFields is just a convenience parameter for the helper function
+  // Each field will be flattened into the string format: key=value~key2=value2
+  Object.entries(customFields).forEach(([key, value]) => {
+    if (value) {
+      parts.push(`${key}=${encodeURIComponent(String(value))}`);
+    }
+  });
+  
+  // Returns a string like: "email=john@example.com~phone=+1234567890~department=Engineering"
+  return parts.join("~");
+};
+```
+
+**Important:** The `customFields` parameter is **NOT** passed as an object to the widget. It's just a convenient way to pass multiple additional fields to the helper function. The function flattens everything into a single string format.
+
+**Usage in your application:**
+
+```jsx
+import { ChatWidget } from "@data-netmonk/mona-chat-widget";
+import "@data-netmonk/mona-chat-widget/dist/style.css";
+import { buildChatWidgetData } from "./helpers/chatWidget";
+
+function App() {
+  // Get user data from your auth system, state, or props
+  const user = {
+    id: "user123",
+    name: "John Doe",
+    email: "john@example.com",
+    phone: "+628123456789"
+  };
+  
+  // Build the data string with custom variables only
+  const customData = buildChatWidgetData({
+    email: user.email,
+    phone: user.phone,
+    customFields: {
+      department: "Engineering",
+      role: "Developer",
+      company: "Acme Corp"
+    }
+  });
+  
+  // customData is now a STRING like:
+  // "email=john@example.com~phone=%2B628123456789~department=Engineering~role=Developer~company=Acme%20Corp"
+
+  return (
+    <ChatWidget 
+      userId={user.id}
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
+      authUrl="https://api.example.com/login/chatwidget"  // Direct prop
+      username={user.name}  // Direct prop
+      data={customData}  // Only additional variables
+    />
+  );
+}
+```
+
+**With conditional authentication:**
+
+```jsx
+function App() {
+  const authUrl = import.meta.env.VITE_CHAT_AUTH_ENABLED === "true" 
+    ? import.meta.env.VITE_CHAT_AUTH_URL 
+    : null;
+  
+  const customData = buildChatWidgetData({
+    email: getCurrentUser().email,
+    customFields: {
+      department: "Sales"
+    }
+  });
+
+  return (
+    <ChatWidget 
+      userId={getCurrentUser().id}
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl={import.meta.env.VITE_WEBHOOK_URL}
+      authUrl={authUrl}  // Direct prop (conditionally set)
+      username={getCurrentUser().name}  // Direct prop
+      data={customData}  // Only additional variables
+    />
+  );
+}
+```
+
+**The helper function handles:**
+- ✅ Proper formatting with `~` separators
+- ✅ URL encoding for special characters
+- ✅ Conditional parameter inclusion (only adds if value exists)
+- ✅ Support for dynamic custom fields
+- ✅ Type safety and documentation via JSDoc comments
+
+### Standalone app (for demonstration)
+
+1. **How to run locally** (access at `http://localhost:${PORT}/${APP_PREFIX}`)
+
+   ```
+   npm run dev
+   ```
+
+2. **How to build as a standalone app** (build file at `/dist-app` directory)
+
+   ```
+   npm run build-app
+   ```
+
+3. **How to serve standalone app** (access at `http://localhost:${PORT}/${APP_PREFIX}`)
+
+   ```
+   npm run serve
+   ```
+
+4. **How to run on docker** (access at `http://localhost:${PORT}/${APP_PREFIX}`)
+
+   ```
+   docker-compose up --build
+   ```
+
+---