mysampark_chat 1.0.0

Official MySampark Chat Widget for Flutter. Add AI-powered live chat with human agent takeover, typing indicators, lead forms, and real-time WebSocket support.

mysampark_chat

Official MySampark Chat Flutter plugin — Add AI-powered live chat with human agent takeover, typing indicators, pre-chat surveys, lead forms, and real-time WebSocket support to any Flutter app in minutes.

---

✨ Features

• 🤖 AI-powered replies — instant responses via your trained chatbot
• 👨‍💼 Human agent live takeover — agents reply in real-time via WebSocket
• ⌨️ Typing indicator — animated 3-dot bounce while AI/agent is responding
• 📋 Pre-chat survey gate — collect visitor info before first message (admin controlled)
• 📝 In-chat lead form — name / email / phone capture after N messages
• 💬 Conversation starters — quick-reply chips to help visitors start a chat
• 📜 Chat history — load previous messages with scroll-up pagination
• 🟢 Online / Offline status — live indicator in the chat header
• 🖼️ Logo & branding — logo, colors, widget name all synced from your admin dashboard
• 🔐 HMAC identity — verified logged-in users skip survey & lead form automatically
• 💾 Session persistence — conversation resumes across app restarts
• 🫧 Floating bubble launcher — drop-in FAB that opens chat as a bottom sheet

---

🚀 Installation

Add to your pubspec.yaml:

dependencies:
  mysampark_chat: ^1.0.0

Run:

flutter pub get

---

🔧 Usage

Option A — Floating Bubble (recommended)

Drop it as your Scaffold's floatingActionButton and it renders a branded chat bubble:

import 'package:mysampark_chat/mysampark_chat.dart';

Scaffold(
  body: YourAppBody(),
  floatingActionButton: MySamparkChatBubble(
    widgetKey: 'YOUR_WIDGET_KEY',   // from MySampark dashboard

    // ── Optional: for logged-in users ──────────────────────────────────
    // userHash MUST be generated on your server — never in the app.
    userId:    currentUser.id,
    userHash:  currentUser.chatHash,  // hash_hmac('sha256', userId, widgetSecret)
    userName:  currentUser.name,
    userEmail: currentUser.email,
    // ───────────────────────────────────────────────────────────────────
  ),
);

Option B — Full Screen Chat Page

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => MySamparkChatScreen(
      widgetKey: 'YOUR_WIDGET_KEY',

      // Optional — logged-in user identity
      userId:    currentUser.id,
      userHash:  currentUser.chatHash,
      userName:  currentUser.name,
      userEmail: currentUser.email,
    ),
  ),
);

Option C — Anonymous visitor (no login required)

// Just the widgetKey — everything else is optional
MySamparkChatBubble(widgetKey: 'YOUR_WIDGET_KEY');

---

🔐 Generating userHash (Security — Important)

⚠️ Never put your widgetSecret inside the Flutter app. Always generate the userHash on your backend server and send it to the app via your login API.

PHP / Laravel:

$chatHash = hash_hmac('sha256', (string) $user->id, env('MYSAMPARK_WIDGET_SECRET'));
// Return it in your login API response

Node.js:

const crypto = require('crypto');
const chatHash = crypto
  .createHmac('sha256', process.env.MYSAMPARK_WIDGET_SECRET)
  .update(String(userId))
  .digest('hex');

Then include chatHash in your login API response and pass it to the widget:

// After login API call:
MySamparkChatBubble(
  widgetKey: 'YOUR_WIDGET_KEY',
  userId:    user.id,
  userHash:  user.chatHash,   // ← came from your server
  userName:  user.name,
  userEmail: user.email,
);

---

🎨 What the Admin Dashboard Controls

Everything is configured from your MySampark dashboard — no code changes needed in the Flutter app:

Admin Setting	Effect in Flutter App
Primary color	Bubble, header, buttons, focus borders
Widget name	AppBar title
Logo	AppBar avatar & survey screen
Welcome message	Empty state text
Online / Offline text	Status indicator in header
Conversation starters	Quick-reply chips
Pre-chat survey	Survey overlay before first message
Collect name / email / phone	Lead form fields
Lead form skippable	Skip button visibility
AI on / off	AI reply vs human-only mode

---

📦 Package Structure

lib/
├── mysampark_chat.dart           ← Public exports
└── src/
    ├── models.dart               ← ChatMessage, WidgetConfig
    ├── chat_service.dart         ← REST API + WebSocket handler
    ├── chat_screen.dart          ← Full-screen chat UI
    └── chat_bubble_launcher.dart ← Floating bubble widget

---

🌐 API Endpoints Used

Method	Endpoint	Purpose
POST	/api/chatbot/init	Initialize session, get widget config
GET	/api/chatbot/history	Load past messages (paginated)
POST	/api/chatbot/message	Send message, receive AI reply
POST	/api/chatbot/lead	Submit name / email / phone
WSS	/ws/chat	Real-time agent messages & typing events

---

🤝 Logged-in vs Anonymous Users

Behaviour	Logged-in (with userHash)	Anonymous
Pre-chat survey	⏭️ Skipped automatically	✅ Shown (if enabled)
Lead form	⏭️ Skipped automatically	✅ Shown after 3 messages
Conversation thread	🔗 Same thread across devices	🆕 New per session
Inbox display name	Real name from identity	"Visitor...xyz"

---

📄 License

MIT License © 2026 MySampark