iServe Chatbot

A reusable Flutter package for integrating a chatbot experience into Flutter applications.

The package provides a ready-to-use chatbot UI with conversation handling, interactive options, knowledge-base results, loading states, error handling, and customizable theming.

Features

  • 💬 Ready-to-use chatbot UI
  • 🔄 Conversation and session management
  • 🔘 Interactive chatbot options
  • 📚 Knowledge-base result cards
  • ⏳ Loading and typing indicators
  • ❌ Error handling
  • 📜 Conversation history
  • 🎨 Customizable theme
  • 📱 Responsive UI
  • 🧩 BLoC-based state management
  • 🔌 Simple integration

Installation

Add the package to your application's pubspec.yaml:

dependencies:
  iserve_chatbot: ^0.0.3

Then run:

flutter pub get

Usage

Import the package:

import 'package:iserve_chatbot/iserve_chatbot.dart';

Initialize the chatbot:

IserveChatbot(
  user: const ChatbotUser(
    orgId: '<organization-id>',
    userId: '<user-id>',
    contactId: '<contact-id>',
    email: '<user-email>',
    orgCode: '<organization-code>',
  ),
)

Example:

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: IserveChatbot(
        user: const ChatbotUser(
          orgId: '<organization-id>',
          userId: '<user-id>',
          contactId: '<contact-id>',
          email: '<user-email>',
          orgCode: '<organization-code>',
        ),
      ),
    );
  }
}

The host application only needs to provide the required user context. The package handles the chatbot's internal state, API communication, conversation flow, and UI.

User Configuration

ChatbotUser provides the context required by the chatbot.

const ChatbotUser(
  orgId: '<organization-id>',
  userId: '<user-id>',
  contactId: '<contact-id>',
  email: '<user-email>',
  orgCode: '<organization-code>',
)

Available fields

Field Type Description
orgId String Organization identifier
userId String User identifier
contactId String Contact identifier
email String User email
orgCode String Organization code

Note: The values above are placeholders. Replace them with values from your application's authenticated user context.

Custom Theme

The chatbot supports customization through IserveChatbotTheme.

IserveChatbot(
  user: const ChatbotUser(
    orgId: '<organization-id>',
    userId: '<user-id>',
    contactId: '<contact-id>',
    email: '<user-email>',
    orgCode: '<organization-code>',
  ),
  theme: const IserveChatbotTheme(
    backgroundColor: Colors.white,
    botBubbleColor: Color(0xFFF1F3F5),
    userBubbleColor: Color(0xFF1976D2),
    botTextColor: Colors.black87,
    userTextColor: Colors.white,
    sendButtonColor: Color(0xFF1976D2),
  ),
)

The theme can customize:

  • Chat background
  • Bot message bubbles
  • User message bubbles
  • Text colors
  • Option buttons
  • Input field
  • Send button
  • Knowledge-base cards
  • Error messages
  • Border radius
  • Padding

If no custom theme is provided, the package uses its default theme.

Architecture

The package uses a layered architecture:

┌─────────────────────────────┐
│       IserveChatbot         │
│        Public API           │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│        ChatbotView          │
│             UI              │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│        ChatbotBloc          │
│       State Management      │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│     ChatbotRepository       │
│      API Communication      │
└─────────────────────────────┘

The BLoC, repository, API communication, and internal widgets are implementation details of the package.

Applications should interact with the package through its public API.

Project Structure

iserve_chatbot/
├── lib/
│   ├── iserve_chatbot.dart
│   └── src/
│       ├── api/
│       ├── bloc/
│       ├── models/
│       ├── theme/
│       └── widgets/
│
├── example/
├── test/
├── README.md
├── CHANGELOG.md
├── LICENSE
└── pubspec.yaml

Example

The package includes an example application demonstrating basic integration and usage.

Run the example:

cd example
flutter pub get
flutter run

Development

Get the package dependencies:

flutter pub get

Run tests:

flutter test

Validate the package before publishing:

dart pub publish --dry-run

Versioning

This package follows Semantic Versioning.

Versions use the following format:

MAJOR.MINOR.PATCH

For example:

1.2.3
  • MAJOR — breaking changes
  • MINOR — backward-compatible features
  • PATCH — backward-compatible bug fixes

For example:

1.0.0 → 1.0.1   # Bug fix
1.0.1 → 1.1.0   # New feature
1.1.0 → 2.0.0   # Breaking change

Release notes for each version are documented in CHANGELOG.md.

Requirements

  • Flutter
  • Dart SDK >=3.10.1 <4.0.0

License

See LICENSE for license information.

Contributing

Contributions, issues, and feature requests are welcome.

Please follow the project's development guidelines and submit changes through the appropriate repository workflow.

Libraries

iserve_chatbot