Conferbot Flutter SDK

Native Flutter SDK for embedding Conferbot AI chatbots into iOS and Android applications.

---

Features

• Drop-in Chat Widget -- Full-featured chat UI in a single widget
• Headless SDK -- Provider-based state management for fully custom UIs
• Real-time Messaging -- Socket.IO powered communication
• Live Agent Handover -- Seamless transition to human agents with queue status and pre-chat forms
• Offline Support -- Message queuing and automatic retry when connectivity returns
• Voice Messages -- Record, send, and play back voice messages
• Rich Media -- Image viewer, video player, audio player, and file attachments
• Markdown Rendering -- Full markdown support with syntax-highlighted code blocks
• Knowledge Base -- Searchable help center with categories and article detail views
• Analytics -- Session and event tracking with automatic batched uploads
• Theming -- Light and dark themes out of the box, fully customizable
• 51 Node Types -- Complete node flow engine matching the Conferbot web widget
• Session Persistence -- Chat history survives app restarts via Hive storage
• Message Pagination -- Efficient loading of large conversation histories

Requirements

Platform	Minimum Version
Flutter	3.10
Dart	3.0
iOS	12.0
Android	API 21

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  conferbot_flutter: ^1.0.0

Then run:

flutter pub get

Getting Your API Key and Bot ID

You need two credentials to use the SDK:

1. Log in to Conferbot Dashboard
2. Create or select a bot from the dashboard
3. Find your Bot ID: Go to Bot Settings > General -- the Bot ID is displayed at the top
4. Find your API Key: Go to Workspace Settings > API Keys -- copy the key starting with conf_

Quick Start

1. Drop-in ChatWidget

The fastest way to get started. Wrap your app with ConferBotProvider and push the ChatWidget:

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:conferbot_flutter/conferbot_flutter.dart';

void main() {
  runApp(
    ChangeNotifierProvider(
      create: (_) => ConferBotProvider(
        apiKey: 'YOUR_API_KEY',
        botId: 'YOUR_BOT_ID',
      ),
      child: MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: HomeScreen(),
    );
  }
}

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          Navigator.push(
            context,
            MaterialPageRoute(
              builder: (_) => ChangeNotifierProvider.value(
                value: context.read<ConferBotProvider>(),
                child: ChatWidget(
                  title: 'Support',
                  placeholder: 'Type your message...',
                  showTimestamps: true,
                ),
              ),
            ),
          );
        },
        child: Icon(Icons.chat),
      ),
    );
  }
}

2. Floating Widget (FAB)

A floating action button that overlays on your app. Tapping opens the chat in a modal bottom sheet. Reads server customizations automatically (color, icon, CTA text, position).

import 'package:conferbot_flutter/conferbot_flutter.dart';
import 'package:provider/provider.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: ChangeNotifierProvider(
        create: (_) => ConferBotProvider(
          apiKey: 'YOUR_API_KEY',
          botId: 'YOUR_BOT_ID',
        ),
        child: ConferBotFAB(
          child: Scaffold(
            appBar: AppBar(title: Text('My App')),
            body: Center(child: Text('Your app content')),
          ),
        ),
      ),
    );
  }
}

3. Headless SDK (Custom UI)

Use ConferBotProvider directly to build your own chat interface:

final provider = context.watch<ConferBotProvider>();

// Read state
final messages = provider.record;
final isConnected = provider.isConnected;
final agent = provider.currentAgent;

// Send a message
await provider.sendMessage('Hello!');

// Request live agent handover
provider.initiateHandover(message: 'I need help with billing');

// Listen to events
provider.on(SocketEvents.botResponse, (data) {
  // Handle bot response
});

3. Mix and Match

Combine pre-built widgets with your own components:

Column(
  children: [
    ChatHeader(
      agent: provider.currentAgent,
      onClose: () => Navigator.pop(context),
    ),
    Expanded(
      child: MessageList(messages: provider.record),
    ),
    ChatInput(onSend: provider.sendMessage),
  ],
)

Individual widgets available: ChatHeader, MessageList, MessageBubble, ChatInput, TypingIndicator, ConnectionStatus, OfflineIndicator, Avatar, and more.

Configuration

ConferBotConfig

Pass a ConferBotConfig to customize SDK behavior:

ConferBotProvider(
  apiKey: 'YOUR_API_KEY',
  botId: 'YOUR_BOT_ID',
  config: ConferBotConfig(
    enableNotifications: true,
    enableOfflineMode: true,
    enablePersistence: true,
    enablePagination: true,
    enableAnalytics: true,
    autoConnect: true,
    reconnectionAttempts: 5,
    reconnectionDelay: 1000,
    analyticsFlushInterval: Duration(seconds: 30),
  ),
)

Option	Type	Default	Description
enableNotifications	bool	false	Enable push notification support
enableOfflineMode	bool	false	Queue messages when offline
enablePersistence	bool	false	Persist chat history across app restarts
enablePagination	bool	false	Paginate large message histories
enableAnalytics	bool	false	Track session and event analytics
autoConnect	bool	true	Connect to socket automatically
reconnectionAttempts	int?	5	Max socket reconnection attempts
reconnectionDelay	int?	1000	Delay between reconnection attempts (ms)

Theming

Built-in Themes

// Light theme (default)
ChatWidget(theme: defaultTheme);

// Dark theme
ChatWidget(theme: darkTheme);

Custom Theme

final customTheme = ConferBotTheme(
  brightness: Brightness.light,
  colors: ConferBotColors(
    primary: Color(0xFF6366F1),
    userBubble: Color(0xFF6366F1),
    botBubble: Color(0xFFF3F4F6),
    background: Color(0xFFFFFFFF),
    text: Color(0xFF111827),
  ),
);

ChatWidget(theme: customTheme);

Push Notifications

Register a device token (from Firebase, APNs, or any provider) to receive messages when the app is in the background:

final provider = context.read<ConferBotProvider>();
await provider.registerPushToken(deviceToken);

Offline Support

When enableOfflineMode is set to true, the SDK automatically queues outgoing messages during network interruptions and delivers them when connectivity is restored. The OfflineIndicator widget provides visual feedback to users.

Knowledge Base

Display a searchable help center within your app:

KnowledgeBaseScreen()

The knowledge base supports category filtering, full-text search, and article detail views.

Voice Messages

Voice recording and playback are built in. The VoiceInputWidget handles microphone permissions, recording, and sending. The VoicePlayer widget renders playback controls for received voice messages.

VoiceInputWidget(onSend: (audioPath) {
  // Send voice message
})

Analytics

When enableAnalytics is true, the SDK tracks session events and batches them for upload at configurable intervals. Access analytics data through the AnalyticsProvider.

Socket Events

Subscribe to real-time events for fine-grained control:

final provider = context.read<ConferBotProvider>();

provider.on(SocketEvents.botResponse, (data) { /* ... */ });
provider.on(SocketEvents.agentAccepted, (data) { /* ... */ });
provider.on(SocketEvents.agentMessage, (data) { /* ... */ });
provider.on(SocketEvents.agentLeft, (data) { /* ... */ });
provider.on(SocketEvents.agentTypingStatus, (data) { /* ... */ });
provider.on(SocketEvents.chatEnded, (data) { /* ... */ });

API Reference

Full API documentation is available in the docs/ directory:

• API Reference -- Provider methods, models, and services
• Architecture -- SDK internals and design decisions
• Components -- Widget catalog and usage
• Examples -- Additional integration patterns
• Changelog -- Version history

Example App

A fully working example application is included in the example/ directory.

Running the Example

# 1. Clone the repo
git clone https://github.com/conferbot/flutter-sdk.git
cd flutter-sdk

# 2. Install dependencies
flutter pub get

# 3. Configure your bot credentials
#    Open example/lib/main.dart and replace:
#      apiKey: 'test_key'
#      botId: '69e8503cf33718a92ea792fe'
#    with your own credentials from the Conferbot dashboard.

# 4. (Optional) Point to production server
#    Remove the ConferBotEndpoints.configure() call in main.dart.
#    By default, the SDK connects to https://embed.conferbot.com

# 5. Run on a connected device or emulator
cd example
flutter run

What the Example Shows

Screen	Pattern	Description
Chat Widget	Drop-in	Full chat UI in a bottom sheet -- one widget, zero config
Headless	Provider-based	Custom UI with ConferBotProvider and Consumer for full control
Custom	Mix & match	Pre-built widgets (MessageList, ChatInput) in a custom layout

Documentation

For full documentation, guides, and platform setup instructions, visit:

https://docs.conferbot.com/mobile/flutter

Contributing

We welcome contributions. Please open an issue first to discuss proposed changes before submitting a pull request.

1. Fork the repository
2. Create a feature branch
3. Run flutter test and flutter analyze before submitting
4. Open a pull request against main

License

Apache 2.0 -- see LICENSE for details.

Support

• GitHub Issues: https://github.com/conferbot/flutter-sdk/issues
• Email: support@conferbot.com
• Documentation: https://docs.conferbot.com