💬 WS Chat Flutter #

A comprehensive real-time chat widget package for Flutter with AI assistance and seamless customer service handover, built with Socket.IO.

✨ Features #

🎯 Customer Chat Screen #

• 🤖 AI-Powered Responses - Instant automated replies using AI
• 👤 Human CS Handover - Seamless transfer to human agents
• 📱 Responsive Design - Works on phones, tablets, and web
• 💬 Real-time Messaging - Instant message delivery
• ✅ Read Receipts - Know when messages are read
• 📜 Chat History - Persistent conversation history
• 🎨 Customizable Theme - Adjust colors to match your brand
• 🌐 Full Screen Experience - Native screen implementation

👨‍💼 CS Dashboard Screen #

• 📊 Multi-Chat Management - Handle multiple conversations
• 🔄 Real-time Updates - Instant message and status updates
• 🤖 AI Summary - View AI conversation summaries
• 🔔 Notifications - In-app notifications for new messages
• ✅ Message Read Tracking - See when customers read messages
• 🎯 Smart Sorting - Auto-sorted by latest activity
• 📱 Responsive Layout - Desktop and mobile optimized

📦 Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  ws_chat_flutter: ^1.0.0

Then run:

flutter pub get

🚀 Quick Start #

Customer Chat Screen #

import 'package:ws_chat_flutter/ws_chat_flutter.dart';

// Navigate to chat screen
Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => ChatScreen(
      serverUrl: 'https://your-server.com',
      customerId: 'customer_123',
      customerName: 'John Doe',
      title: 'Customer Support',
      primaryColor: Color(0xFF4F46E5),
    ),
  ),
);

CS Dashboard Screen #

import 'package:ws_chat_flutter/ws_chat_flutter.dart';

// Navigate to CS dashboard
Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => CSDashboardScreen(
      serverUrl: 'https://your-server.com',
      csUserId: 'cs_001',
      csName: 'Agent Sarah',
      primaryColor: Color(0xFF10B981),
    ),
  ),
);

📱 Usage Examples #

Example 1: In-App Support Button #

import 'package:flutter/material.dart';
import 'package:ws_chat_flutter/ws_chat_flutter.dart';

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('My App'),
        actions: [
          IconButton(
            icon: Icon(Icons.support_agent),
            onPressed: () {
              Navigator.push(
                context,
                MaterialPageRoute(
                  builder: (context) => ChatScreen(
                    serverUrl: 'https://your-server.com',
                    customerId: 'user_${userId}',
                    customerName: userName,
                  ),
                ),
              );
            },
          ),
        ],
      ),
      body: Center(
        child: Text('Welcome to My App'),
      ),
    );
  }
}

Example 2: Embedded in Navigation #

import 'package:flutter/material.dart';
import 'package:ws_chat_flutter/ws_chat_flutter.dart';

class MainScreen extends StatefulWidget {
  @override
  _MainScreenState createState() => _MainScreenState();
}

class _MainScreenState extends State<MainScreen> {
  int _currentIndex = 0;

  final List<Widget> _screens = [
    HomeScreen(),
    ChatScreen(
      serverUrl: 'https://your-server.com',
      customerId: 'customer_123',
      customerName: 'John Doe',
      showBackButton: false,
    ),
    ProfileScreen(),
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: _screens[_currentIndex],
      bottomNavigationBar: BottomNavigationBar(
        currentIndex: _currentIndex,
        onTap: (index) => setState(() => _currentIndex = index),
        items: [
          BottomNavigationBarItem(icon: Icon(Icons.home), label: 'Home'),
          BottomNavigationBarItem(icon: Icon(Icons.chat), label: 'Support'),
          BottomNavigationBarItem(icon: Icon(Icons.person), label: 'Profile'),
        ],
      ),
    );
  }
}

Example 3: CS Agent Login Flow #

import 'package:flutter/material.dart';
import 'package:ws_chat_flutter/ws_chat_flutter.dart';

class CSLoginPage extends StatelessWidget {
  final String agentId;
  final String agentName;

  const CSLoginPage({
    required this.agentId,
    required this.agentName,
  });

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            // Navigate to CS Dashboard
            Navigator.pushReplacement(
              context,
              MaterialPageRoute(
                builder: (context) => CSDashboardScreen(
                  serverUrl: 'https://your-server.com',
                  csUserId: agentId,
                  csName: agentName,
                  primaryColor: Colors.green,
                ),
              ),
            );
          },
          child: Text('Start CS Dashboard'),
        ),
      ),
    );
  }
}

🎨 Customization #

Custom Colors #

ChatScreen(
  serverUrl: 'https://your-server.com',
  customerId: 'customer_123',
  customerName: 'John Doe',
  primaryColor: Color(0xFFFF6B6B), // Custom brand color
)

Custom Title #

ChatScreen(
  serverUrl: 'https://your-server.com',
  customerId: 'customer_123',
  customerName: 'John Doe',
  title: 'Talk to Us', // Custom title
)

Hide Back Button #

ChatScreen(
  serverUrl: 'https://your-server.com',
  customerId: 'customer_123',
  customerName: 'John Doe',
  showBackButton: false, // Useful for embedded screens
)

🔧 Backend Requirements #

This package requires a Socket.IO server with the following events:

Customer Events (Emit) #

• start_chat - Initialize chat session
• customer_message - Send customer message
• get_customer_chat_history - Request chat history
• mark_message_read - Mark message as read

CS Events (Emit) #

• cs_login - CS agent login
• cs_logout - CS agent logout
• cs_select_room - Select chat room
• cs_send_message - Send CS message
• cs_get_all_rooms - Get all chat rooms
• cs_mark_messages_read - Mark messages as read

Server Response Events (Listen) #

• chat_started - Chat session created
• receive_message - New message received
• ai_typing - AI is typing indicator
• cs_assigned - CS agent assigned
• messages_read_by_cs - Messages read by CS
• customer_chat_history - Chat history data
• cs_chat_rooms - Available chat rooms
• cs_chat_history - Room chat history
• customer_message_to_cs - Customer message notification
• new_customer_chat - New chat notification
• cs_message_sent - Message sent confirmation
• message_read_by_customer - Read receipt

📱 Platform Support #

🔒 Security Notes #

• Always use HTTPS in production
• Implement proper authentication for CS dashboard
• Validate all user inputs on the server
• Use environment variables for sensitive data
• Implement rate limiting on the server

🐛 Troubleshooting #

Connection Issues #

// Check if server URL is correct
// Ensure Socket.IO server is running
// Verify CORS settings on server

Messages Not Appearing #

// Verify customerId/csUserId are unique
// Check event names match server implementation
// Enable debug logging: print() statements in SocketService

📄 API Reference #

ChatScreen Properties #

CSDashboardScreen Properties #

🤝 Contributing #

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📜 License #

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author #

Your Name

• Email: your.email@example.com
• GitHub: @yourusername

🙏 Acknowledgments #

• Built with Socket.IO Client
• Inspired by modern chat interfaces
• Thanks to the Flutter community

📞 Support #

For issues and questions:

• 🐛 Report bugs
• 💬 Discussions
• 📧 Email: support@example.com

🗺️ Roadmap #

• ❌ File upload support
• ❌ Voice message support
• ❌ Video call integration
• ❌ Chat analytics
• ❌ Multi-language support
• ❌ Emoji picker
• ❌ Message reactions
• ❌ Typing indicators enhancement
• ❌ Push notifications

Made with ❤️ using Flutter

Version: 1.0.0
Last Updated: November 2024