FlowCXP Atrium Widget

A Flutter package for integrating FlowCXP's advanced customer support chat widget into your Flutter applications. This package provides real-time messaging, dynamic forms, file attachments, and seamless authentication for enterprise-grade customer support experiences.

Features

  • Real-time Chat Communication - Socket.io powered live messaging with agents
  • Dynamic Form Rendering - Automatically render forms based on server templates
  • Attachment Previews - Displays attachments returned by the server
  • Message History - Paginated loading of chat history with deduplication
  • Theme Integration - Uses your app theme and renders in an overlay
  • Cross-platform Support - Works on iOS, Android, Web, and Desktop
  • Form Submission - Dynamic form handling with validation
  • Error Handling - Comprehensive error states and retry mechanisms

Installation

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

dependencies:
  flowcxp_atrium_widget: ^0.0.1

Then run:

flutter pub get

Getting Started

1. Get a valid appId

Customers can get a valid appId at https://www.flowcxp.com.

2. Import the package

import 'package:flowcxp_atrium_widget/flowcxp_atrium_widget.dart';

3. Add the widget

The widget creates its own Riverpod container internally (and will automatically attach to your app's ProviderScope if you already use Riverpod).

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

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: ChatScreen(),
    );
  }
}

class ChatScreen extends StatelessWidget {
  const ChatScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Customer Support')),
      body: const Center(child: Text('Your app content')),

      // Add the widget anywhere under a `MaterialApp`/`Navigator` (it inserts an
      // `OverlayEntry` and renders nothing inline).
      floatingActionButton: FlowCXPChatWidget(appId: 'your-app-id'),
    );
  }
}

4. Optional configuration

FlowCXPChatWidget(
  appId: 'your-app-id',
  env: 'uat', // defaults to 'production'
  title: 'Live Support', // overrides server-provided header title
  onFormSubmitted: (formData) {
    print('Form submitted: $formData');
  },
  onMessageSent: (message) {
    print('Message sent: ${message.content}');
  },
)

API Reference

FlowCXPChatWidget

The main widget component. It inserts an overlay entry and renders the chat UI inside that overlay.

Properties

  • appId (String, required): Your FlowCXP application ID
  • env (String, optional): "production" (default) or "uat"
  • title (String?, optional): Overrides the server-provided header title
  • onMessageSent (Function(ChatMessage)?, optional): Called after a message is successfully sent
  • onFormSubmitted (Function(Map<String, dynamic>)?, optional): Called after a form is submitted

Platform Support

  • iOS: ✅ Fully supported
  • Android: ✅ Fully supported
  • Web: ✅ Fully supported with browser WebSocket
  • Windows: ✅ Fully supported
  • macOS: ✅ Fully supported
  • Linux: ✅ Fully supported

Requirements

  • Flutter SDK: >=3.10.8
  • Dart SDK: ^3.10.8
  • HTTP client for API communication
  • Socket.io client for real-time communication

Example App

See the example/ directory for a complete Flutter application demonstrating all features:

  • Basic chat interface
  • Authentication flow
  • Form rendering and submission
  • File attachment handling
  • Error states and loading indicators

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Submit a pull request

License

This package is licensed under the MIT License. See the LICENSE file for details.

Changelog

See CHANGELOG.md for a detailed history of changes.

Libraries

flowcxp_atrium_widget