flowcxp_atrium_widget 0.0.1-beta.1

A flutter package for the atrium chat widget powered by Flow CXP.

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.