flutter_chat_io 2.3.0

Live customer support for Flutter apps with Slack integration. Users chat in-app, your team responds in Slack.

FlutterChatIO

Live customer support for Flutter apps with Slack integration. Your users chat in-app, your team responds in Slack.

What is FlutterChatIO?

FlutterChatIO brings live customer support directly into your Flutter app. Unlike traditional chat tools that require separate helpdesk software, FlutterChatIO routes all conversations to your existing Slack workspace. Your entire team can participate in support conversations without learning new tools or paying per-seat fees.

Why FlutterChatIO?

• Slack-native support - Messages from your app appear in Slack channels. Reply from Slack, and users see responses instantly in the app.
• Unlimited operators - Any Slack workspace member can help customers. No agent seat limits or restrictive pricing.
• Quick setup - Go live in under an hour. Connect Slack, add the widget, start chatting.
• Automatic context - Every conversation includes user details, device type, app version, and custom data you provide.
• Cross-platform - Single Flutter widget works on iOS, Android, and Web.

How It Works

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Your Flutter   │────▶│   FlutterChatIO  │────▶│  Your Slack     │
│      App        │◀────│     Service      │◀────│   Workspace     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
     User sends              Real-time              Team replies
      message                  sync                  in Slack

1. User opens chat in your app and sends a message
2. Message appears in your designated Slack channel with user context
3. Any team member replies in Slack
4. User sees the response instantly in the app

Getting Started

1. Set Up FlutterChatIO

Visit flutterchat.io to:

• Connect your Slack workspace
• Create a project and get your client token
• Configure the Slack channel for incoming messages

2. Install the SDK

Add flutter_chat_io to your pubspec.yaml:

dependencies:
  flutter_chat_io: ^2.4.0

flutter pub get

3. Initialize

import 'package:flutter_chat_io/flutter_chat_io.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  FlutterChatIO.initialize(
    clientId: 'your-client-id',
    clientToken: 'your-client-token',
  );

  runApp(MyApp());
}

4. Identify Users (Recommended)

Provide user context so your team knows who they're talking to:

FlutterChatIO.setUserId(userId: 'user-123');
FlutterChatIO.setUserInfo(
  email: '[e-mail]',
  userName: 'John Doe',
);

5. Show the Chat

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => const FlutterChatIOChat(),
  ),
);

Features

Real-time Messaging

Messages sync instantly between your app and Slack via WebSocket with automatic reconnection on connection loss.

Message History

Conversations persist across sessions. Users see their full chat history when they return.

Image Attachments

Users can share images directly in chat with automatic upload handling.

Offline Contact Form

When your team is offline, users can leave their contact information for follow-up.

Connection Status

Visual indicators show users when support is online, offline, or connecting.

Theming

Customize the appearance to match your app:

FlutterChatIOChat(
  theme: FlutterChatIOTheme(
    // AppBar
    appBarColor: Colors.indigo,
    appBarTitle: 'Help Center',

    // Message bubbles
    outgoingMessageColor: Colors.indigo,
    incomingMessageColor: Colors.grey.shade200,

    // Status indicators
    onlineColor: Colors.green,
    offlineColor: Colors.red,
    connectingColor: Colors.orange,

    // Empty state
    emptyStateTitle: 'How can we help?',
    emptyStateSubtitle: 'Send us a message to get started',
  ),
)

Theme Properties

Category	Properties
AppBar	appBarColor, appBarTitle, appBarTitleTextStyle, appBarSubtitleTextStyle, backButtonIcon, backButtonColor
Background	backgroundColor, backgroundGradient
Messages	incomingMessageColor, outgoingMessageColor, incomingMessageTextStyle, outgoingMessageTextStyle, incomingTimeTextStyle, outgoingTimeTextStyle
Status	onlineColor, offlineColor, connectingColor
Input	inputBackgroundColor, inputTextColor, inputHintColor, inputHintText, inputHintStyle, inputTextStyle, cursorColor, keyboardAppearance, sendButtonColor, sendButtonDisabledColor, attachmentIcon, attachmentIconWidget, attachmentIconColor
Empty State	emptyStateTitle, emptyStateSubtitle, emptyStateTitleStyle, emptyStateSubtitleStyle
Offline Form	offlineFormTitle, offlineFormSubtitle, offlineFormButtonText, offlineFormNameHint, offlineFormEmailHint, offlineFormNameEmailError, offlineFormEmailValidError
Chat	supportUserName

Customizing the Input Area

The composer is fully themable. Beyond colors, you can customize the placeholder text, its typography, the blinking text caret, and the attachment button:

FlutterChatIOTheme(
  // Placeholder text and style
  inputHintText: 'Ask us anything…',
  inputHintStyle: const TextStyle(
    fontSize: 14,
    fontStyle: FontStyle.italic,
    color: Color(0xFFB0B0B0),
  ),

  // What the user types
  inputTextStyle: const TextStyle(fontSize: 15, fontWeight: FontWeight.w500),

  // Blinking caret + selection highlight
  cursorColor: Colors.deepPurpleAccent,

  // Replace the attachment icon with any widget, independently of the
  // app bar color.
  attachmentIconWidget: const Icon(Icons.attach_file_rounded),
  attachmentIconColor: Colors.grey, // no longer tied to appBarColor
)

Customizing the Back Button

Either recolor the default back arrow or swap it out entirely:

// Option 1 — just change the color
FlutterChatIOTheme(
  appBarColor: Colors.deepPurple,
  backButtonColor: Colors.amberAccent,
)

// Option 2 — provide a fully custom icon widget
FlutterChatIOTheme(
  appBarColor: Colors.deepPurple,
  backButtonIcon: const Icon(Icons.arrow_back_ios_new),
)

Localization

Customize all text for different languages:

FlutterChatIOTheme(
  // Spanish
  appBarTitle: 'Soporte',
  emptyStateTitle: 'Bienvenido',
  emptyStateSubtitle: 'Envíanos un mensaje para comenzar',
  offlineFormTitle: 'Estamos fuera de línea',
  offlineFormSubtitle: 'Deja tu información de contacto',
  offlineFormButtonText: 'Continuar al chat',
  offlineFormNameHint: 'Tu nombre',
  offlineFormEmailHint: 'Tu email',
  supportUserName: 'Soporte',
)

Dark Theme Example

FlutterChatIOChat(
  theme: FlutterChatIOTheme(
    backgroundColor: const Color(0xFF121212),
    appBarColor: const Color(0xFF1E1E1E),
    inputBackgroundColor: const Color(0xFF2D2D2D),
    inputTextColor: Colors.white,
    inputHintColor: Colors.white54,
    keyboardAppearance: Brightness.dark,
    appBarTitleTextStyle: const TextStyle(
      fontSize: 17,
      fontWeight: FontWeight.w600,
      color: Colors.white,
    ),
    incomingMessageTextStyle: const TextStyle(
      fontSize: 15,
      color: Colors.white,
    ),
    emptyStateTitleStyle: const TextStyle(
      fontSize: 20,
      fontWeight: FontWeight.w600,
      color: Colors.white,
    ),
    emptyStateSubtitleStyle: const TextStyle(
      fontSize: 14,
      color: Colors.white70,
    ),
  ),
)

User Session Management

Setting User Identity

Set user information and custom metadata in a single call:

// After user login
FlutterChatIO.setUserId(userId: user.id);
FlutterChatIO.setUserInfo(
  email: user.email,
  userName: user.displayName,
  customData: {
    'subscription': 'premium',
    'accountType': 'business',
    'signupDate': '2024-01-15',
  },
);

Note: Device information is automatically detected by the SDK.

All this data appears in the user info card in Slack, helping your team understand the user's context at a glance.

Resetting on Logout

void onLogout() {
  FlutterChatIO.reset();
}

Checking Initialization

if (FlutterChatIO.isInitialized) {
  Navigator.push(
    context,
    MaterialPageRoute(builder: (_) => const FlutterChatIOChat()),
  );
}

Auto-detected Information

The SDK automatically detects and sends detailed device information to help your support team debug platform-specific issues. No configuration required.

API Reference

FlutterChatIO

Method	Description
initialize({required String clientId, required String clientToken, String? wsEndpoint, String? httpEndpoint})	Initialize the SDK with your credentials from flutterchat.io
setUserId({required String userId})	Set the current user's unique identifier
setUserInfo({String? email, String? userName, Map<String, String>? customData})	Set user information and custom metadata visible in Slack (device info is auto-detected)
setNotificationToken({required String token})	Register FCM/APNs token via HTTP (non-blocking with background retry)
isFlutterChatIONotification(Map<String, dynamic> data)	Check if notification payload is from FlutterChatIO
reset()	Unregister notification token and clear all user data (non-blocking with background retry)
isInitialized	Check if the SDK is initialized

FlutterChatIOChat

Property	Type	Description
theme	FlutterChatIOTheme	Theme configuration for the chat widget

Roadmap

Planned features for upcoming releases:

• AI Bot Integration - Automated responses and smart routing before human handoff

Push Notifications Setup

FlutterChatIO supports push notifications to notify users when support replies.

Note: Currently only Firebase Cloud Messaging is supported for both Android and iOS. Native APNs integration is not available at this time.

Good to know: Push notifications work for both anonymous and authenticated users. Every device gets a stable anonymous ID (format: anon-{uuid}) that persists permanently. When you call setUserId(), notifications use your real user ID. When you call reset() (logout), the SDK falls back to the anonymous ID - no migration needed.

What You Need to Provide

To enable push notifications, share your Firebase service account JSON file with FlutterChatIO backend.

Firebase Setup (Android & iOS)

Important: Setup requires two different files for different purposes:

• Config files (google-services.json for Android, GoogleService-Info.plist for iOS) - For your app (Section 1)
• Service account JSON - For FlutterChatIO backend (Section 2)

1. Add Your Apps to Firebase

Android:

1. Go to Firebase Console
2. Select your project (or click Add project if you don't have one)
3. Click General → Your apps → Add Android app
4. Enter package name from android/app/build.gradle
5. Download google-services.json
6. Place in android/app/

iOS:

1. In same Firebase project, click Add iOS app
2. Enter Bundle ID from Xcode
3. Download GoogleService-Info.plist
4. Add to ios/Runner/ in Xcode (right-click Runner → Add Files)
5. Upload APNs auth key:
   • Firebase Console → Project Settings → Cloud Messaging → iOS
   • Upload your APNs .p8 key (get from Apple Developer Portal)

These config files are for your app only - do not share with FlutterChatIO.

2. Get Firebase Service Account JSON

This credential file is needed by FlutterChatIO backend to send push notifications:

1. In Firebase Console, go to Project Settings
2. Select Cloud Messaging tab
3. Click Manage Service Accounts (opens Google Cloud Console)
4. Find the service account with name containing firebase-adminsdk
5. Click on that service account to open it
6. Switch to Keys tab
7. Click Add key → Create new key
8. Select JSON format
9. Download the JSON file (this is your service account key)
10. Share this file securely with FlutterChatIO

This is a different file from google-services.json and must be shared with FlutterChatIO backend.

Security: Share via encrypted email, password-protected file transfer, or secure file sharing service.

3. Configure Your Apps

Android:

Kotlin DSL — for .gradle.kts files

android/build.gradle.kts:

buildscript {
    dependencies {
        classpath("com.google.gms:google-services:4.4.4")
    }
}

android/app/build.gradle.kts:

plugins {
    id("com.google.gms.google-services")
}

dependencies {
    implementation(platform("com.google.firebase:firebase-bom:34.7.0"))
    implementation("com.google.firebase:firebase-messaging")
}

Groovy DSL — for .gradle files

android/build.gradle:

buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.4.4'
    }
}

android/app/build.gradle:

plugins {
    id 'com.google.gms.google-services'
}

dependencies {
    implementation platform('com.google.firebase:firebase-bom:34.7.0')
    implementation 'com.google.firebase:firebase-messaging'
}

iOS:

1. Enable capabilities in Xcode:

   • Open ios/Runner.xcworkspace
   • Select Runner target → Signing & Capabilities
   • Add Push Notifications
   • Add Background Modes → Enable Remote notifications

2. Initialize Firebase in AppDelegate.swift:

import UIKit
import Flutter
import FirebaseCore

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    FirebaseApp.configure()
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

Flutter App Integration

Add Dependencies

dependencies:
  flutter_chat_io: ^2.4.0
  firebase_core: ^3.8.1
  firebase_messaging: ^15.1.5

Complete Integration Code

Good to know: Push notifications work for both anonymous and authenticated users. You can register notification tokens immediately - every device gets a stable anonymous ID. When you call setUserId() after authentication, the SDK automatically uses the real user ID for notifications.

import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:flutter_chat_io/flutter_chat_io.dart';

// 1. Background message handler
@pragma('vm:entry-point')
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  await Firebase.initializeApp();
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 2. Initialize Firebase
  await Firebase.initializeApp();
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);

  // 3. Initialize FlutterChatIO
  FlutterChatIO.initialize(
    clientId: 'your-client-id',
    clientToken: 'your-client-token',
  );

  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _setupPushNotifications();
  }

  // 4. Push notifications setup (copy-paste this method)
  Future<void> _setupPushNotifications() async {
    final messaging = FirebaseMessaging.instance;

    await messaging.requestPermission();

    // Register token via HTTP (works for both anonymous and authenticated users)
    // If no user ID set, SDK generates stable anonymous ID automatically
    final token = await messaging.getToken();
    if (token != null) {
      FlutterChatIO.setNotificationToken(token: token);
    }

    // Auto-update token when FCM refreshes
    // SDK automatically unregisters old token and registers new one
    messaging.onTokenRefresh.listen((newToken) {
      FlutterChatIO.setNotificationToken(token: newToken);
    });

    // Handle foreground notifications
    FirebaseMessaging.onMessage.listen((message) {
      if (FlutterChatIO.isFlutterChatIONotification(message.data)) {
        // Show notification or handle as needed
      }
    });

    // Handle notification taps
    FirebaseMessaging.onMessageOpenedApp.listen((message) {
      if (FlutterChatIO.isFlutterChatIONotification(message.data)) {
        Navigator.push(
          context,
          MaterialPageRoute(builder: (_) => FlutterChatIOChat()),
        );
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    // Your app UI
  }
}

Using with Existing Push Notifications

If you already have Firebase push notifications, just add FlutterChatIO filtering:

FirebaseMessaging.onMessage.listen((message) {
  if (FlutterChatIO.isFlutterChatIONotification(message.data)) {
    // FlutterChatIO notification
  } else {
    // Your existing notification handling
  }
});

Both systems use the same Firebase project. Notifications are filtered by the data.source field.

Security

• Never commit firebase-service-account.json to git
• Share credentials with FlutterChatIO via encrypted email or secure file transfer
• Rotate service account keys yearly

Testing

1. Run your app and send a test message
2. Have support reply via Slack
3. Verify you receive a push notification

Issues? Check Firebase Console for errors and verify permissions are granted (iOS).

Requirements

• Flutter 3.10.0 or higher
• Dart 3.0.0 or higher
• FlutterChatIO account (flutterchat.io Dashboard)

License

BSD 3-Clause License - see the LICENSE file for details.

Support

• Website: flutterchat.io
• Documentation: flutterchat.io/docs
• Email: [e-mail]