FMG-CRM Widget (FMG-WIDGET)

This README is for the FMG-CRM project only.

FMG-WIDGET is the widget package used by this monorepo:

• FMG-WIDGET → widget source/build
• FMG-BD → backend APIs/socket server
• FMG-FD → frontend app that embeds the widget

In this project, it provides:

• Start Query: real-time customer chat (Socket.IO)
• Raise Ticket: full-screen support ticket board
• Camera snapshot flow: agent-requested image capture from customer
• Auto user detection: can infer name/email/phone from host page when userData is not passed

Package Information

• Package name: fmg-chat-widget
• Current version: 1.12.0
• License: MIT
• Build outputs:
  • dist/index.js (CommonJS)
  • dist/index.esm.js (ESM)
  • dist/chat-widget.min.js (standalone browser/IIFE)

Monorepo Setup (FMG-CRM)

1) Build widget package (FMG-WIDGET)

cd FMG-WIDGET
npm install
npm run build

2) Use it in frontend (FMG-FD)

Current FMG-FD/package.json still includes bitmax-crm-widget (old package name).

For this project, migrate usage to fmg-chat-widget (or local package linking) so frontend and widget source stay aligned.

React Integration

The package exports two React components:

• ChatCRMWidget
• TicketBoard

Basic usage

import { ChatCRMWidget } from 'fmg-chat-widget';

export default function App() {
  return (
    <ChatCRMWidget
      apiKey={import.meta.env.VITE_CHAT_API_KEY}
      apiUrl={import.meta.env.VITE_API_URL || 'http://localhost:5000'}
      primaryColor="#4F46E5"
      companyName="FMG Support"
    />
  );
}

Optional: ticket board only

import { TicketBoard } from 'fmg-chat-widget';

export default function TicketsPage() {
  return (
    <TicketBoard
      apiKey={import.meta.env.VITE_CHAT_API_KEY}
      apiUrl={import.meta.env.VITE_API_URL || 'http://localhost:5000'}
      primaryColor="#4F46E5"
      userData={{ name: 'John Doe', email: '[email protected]' }}
      onClose={() => {}}
    />
  );
}

Standalone (Vanilla JS / HTML)

Build first:

npm run build

Then include dist/chat-widget.min.js on your page and initialize via global API:

<script src="/path/to/dist/chat-widget.min.js"></script>
<script>
  window.ChatCRMWidget.init({
    apiKey: 'your_api_key',
    apiUrl: 'http://localhost:5000',
    primaryColor: '#4F46E5',
    companyName: 'FMG Support',
    userData: {
      name: 'Guest User',
      email: '[email protected]',
      phone: '+1234567890',
      userId: 'USER_123'
    }
  });
</script>

ChatCRMWidget Props

| Prop | Type | Default | Required | Notes | |---|---|---|---|---| | apiKey | string | - | ✅ | Organization/widget API key | | apiUrl | string | https://your-backend-url.com | ✅ | Backend base URL | | primaryColor | string | #4F46E5 | ❌ | Brand color | | position | string | bottom-right | ❌ | bottom-right, bottom-left, top-right, top-left | | userData | object \| null | null | ❌ | If omitted, widget tries auto-detection/localStorage | | welcomeMessage | string | 👋 Welcome! How can we help you today? | ❌ | Initial UI message | | companyName | string | Support | ❌ | Header label | | autoOpen | boolean | false | ❌ | Open widget by default | | showNotifications | boolean | true | ❌ | Unread badge behavior | | playSound | boolean | false | ❌ | Notification beep | | theme | light \| dark \| auto | light | ❌ | Visual theme | | zIndex | number | 9999 | ❌ | Layering control |

userData shape

{
  name?: string;
  email?: string;
  phone?: string;
  userId?: string;
}

Feature Highlights

Help & Support menu

• Single floating entry point
• Two flows: Start Query and Raise Ticket

Query flow (chat)

• Lazy conversation creation (on first send)
• Socket namespace support for real-time updates
• Typing indicators (agent/customer)
• Query lifecycle states (accepted, transferred, resolved, reopened)
• Optional post-resolution feedback capture

Snapshot capture flow

• Agent can request camera snapshot
• Customer captures image in-widget
• Upload sent to backend webhook endpoint
• Image URL appears inline in chat history

Ticket board

• Full-page overlay experience
• Create and track tickets
• Conversation-style replies on tickets
• Attachment upload support and file validation
• Dark mode compatible

Backend API Expectations

For this project, these are expected from FMG-BD:

Chat / webhook

• POST /api/v1/webhook/guest-conversation
• POST /api/v1/webhook/send-message
• POST /api/v1/webhook/upload-snapshot

Ticketing

• GET /api/v1/email-ticketing/tickets
• POST /api/v1/email-ticketing/tickets
• GET /api/v1/email-ticketing/tickets/:ticketId/messages
• POST /api/v1/email-ticketing/tickets/widget/reply
• GET /api/v1/email-ticketing/attachments/download (for download helper flow)

All protected endpoints should validate your widget/API key (commonly via x-api-key or request body where applicable).

FMG-CRM Specific Notes

• Keep widget code changes in FMG-WIDGET/src/** and rebuild before frontend testing.
• Use FMG-BD as the API/socket base (VITE_API_URL, usually http://localhost:5000 in local dev).
• Update FMG-FD imports/dependency from old bitmax-crm-widget to fmg-chat-widget to avoid drift.

Development

npm install
npm run build
npm run dev

• npm run build: production bundle generation
• npm run dev: rollup watch mode (build:watch)

Notes

• For integration walkthroughs, see:
  • MERN_INTEGRATION_GUIDE.md
  • TICKETING_SYSTEM_GUIDE.md
  • QUICK_REFERENCE.md
• For release notes, see CHANGELOG.md.