Developer Documentation

Add live customer support to your Flutter app in minutes. Your users chat in-app, your team responds in Slack.

Introduction #

FlutterChatIO is a customer support SDK that connects your Flutter app directly to your Slack workspace. When users send messages in your app, they appear in your Slack channel. When your team replies in Slack, users see the response instantly.

Installation #

Add FlutterChatIO to your pubspec.yaml:

dependencies:
  flutter_chat_io: ^2.1.0Copy

Then run:

flutter pub getCopy

Quick Start #

Get up and running in three steps:

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());
}Copy

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

Initialization #

The FlutterChatIO.initialize() method configures the SDK. Call it once at app startup before using any other SDK features.

Parameters

Example

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

Check Initialization Status

if (FlutterChatIO.isInitialized) {
  // SDK is ready
  Navigator.push(context, route);
} else {
  showError('Chat not configured');
}Copy

User Identity #

Provide user context so your team knows who they're talking to in Slack. This information appears alongside messages in your Slack channel.

Setting User ID

Link conversations to your user accounts:

// After user authentication
FlutterChatIO.setUserId(userId: user.id);Copy

Setting User Info

Provide additional context for your support team. Device information is automatically detected by the SDK:

FlutterChatIO.setUserInfo(
  email: '[email protected]',
  userName: 'John Doe',
  customData: {
    'subscription': 'premium',
    'accountType': 'business',
    'signupDate': '2024-01-15',
  },
);Copy

Resetting on Logout

void onLogout() {
  FlutterChatIO.reset();
  // Navigate to login screen
}Copy

Chat Widget #

FlutterChatIOChat is the main widget that displays the chat interface. It handles:

• Real-time messaging via WebSocket
• Message history loading
• Image attachments
• Connection status indicators
• Offline contact form
• Auto-reconnection

FlutterChatIOChat(
  theme: FlutterChatIOTheme(
    appBarTitle: 'Help Center',
    appBarColor: Colors.indigo,
  ),
)Copy

Theming #

Customize the chat appearance using FlutterChatIOTheme:

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',

    // Input field
    inputBackgroundColor: Colors.white,
    sendButtonColor: Colors.indigo,
  ),
)Copy

Localization #

Customize all text content for different languages. You can either manually set all strings or use the built-in localized factory:

Manual Localization

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

Built-in Localization

Use the localized factory constructor for automatic localization:

// Use device locale
FlutterChatIOChat(
  theme: FlutterChatIOTheme.localized(
    Localizations.localeOf(context),
  ),
)

// Or use specific locale
FlutterChatIOChat(
  theme: FlutterChatIOTheme.localized(
    const Locale('es'),
    appBarColor: Colors.indigo, // Still customizable
  ),
)Copy

API Reference #

FlutterChatIO

FlutterChatIOChat

Theme Properties #

AppBar

Background

Messages

Status Indicators

Input Field

Empty State

Offline Form

Chat Configuration

Error Messages

Troubleshooting #

SDK not initialized

If you see an assertion error about initialization, ensure you call FlutterChatIO.initialize() before using the chat widget:

// In main.dart
void main() {
  WidgetsFlutterBinding.ensureInitialized();
  FlutterChatIO.initialize(
    clientId: 'your-client-id',
    clientToken: 'your-client-token',
  );
  runApp(MyApp());
}Copy

Messages not appearing in Slack

If messages aren't appearing in your Slack workspace, check the following:

• Verify your clientId and clientToken are correct
• Check your Slack workspace connection in the dashboard
• Ensure the target Slack channel exists and the bot has access

Connection issues

The SDK automatically reconnects on connection loss. If you're experiencing persistent connection issues, check:

• Device has internet connectivity
• Firewall isn't blocking WebSocket connections to wss://ws.flutterchat.io
• Client token hasn't expired or been revoked