iServe Chatbot

A reusable Flutter package for integrating a chatbot experience into Flutter applications. It provides a ready-to-use chatbot UI with API integration, conversation management, interactive options, knowledge-base results, loading states, error handling, conversation history, and customizable theming.

The package manages its internal BLoC, repository, API communication, session initialization, and chatbot UI, making integration straightforward for existing Flutter applications.

Features

  • 💬 Ready-to-use chatbot UI
  • 🔄 Conversation and session management
  • 🔘 Interactive chatbot options
  • 📚 Knowledge-base result cards
  • ⏳ Loading indicators and typing animations
  • ❌ Dynamic error handling
  • 📜 Conversation history and history menu support
  • 🎨 Customizable chatbot themes
  • 📱 Responsive UI
  • 🧩 BLoC-based state management
  • 🔌 Configurable API base URL and endpoints
  • 💾 Session persistence using SharedPreferences
  • 🔁 Automatic restoration of a previously saved chat session
  • ⚙️ Simple integration with existing Flutter applications

Installation

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

dependencies:
  iserve_chatbot: ^0.1.0

Then run:

flutter pub get

If the package is hosted in a private repository or used locally, configure the appropriate dependency source in your pubspec.yaml.

Getting Started

1. Import the Package

import 'package:flutter/material.dart';
import 'package:iserve_chatbot/iserve_chatbot.dart';

2. Configure the API Endpoints

Create a ChatbotApiCredentials instance with your chatbot backend's base URL and endpoint paths.

const chatbotApiCredentials = ChatbotApiCredentials(
  baseUrl: 'https://your-api.example.com',
  messageEndpoint: '/chat/message',
  optionEndpoint: '/chat/options',
  sessionEndpoint: '/chat/session',
  threadsEndpoint: '/chat/threads',
);

Replace the example URL and endpoint paths with those required by your backend.

Available API Configuration Fields

Field Type Description
baseUrl String Base URL of the chatbot API
messageEndpoint String Endpoint used to send chatbot messages
optionEndpoint String Endpoint used to handle interactive options
sessionEndpoint String Endpoint used to retrieve a chat session
threadsEndpoint String Endpoint used for conversation threads

All five fields are required.

Keeping these values configurable allows the same package to be used with different backend environments without hardcoding endpoint paths.

3. Configure the User

The ChatbotUser model provides the user and organization context required by the chatbot API.

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

Available User Fields

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

Replace these placeholders with values from your application's authenticated user context.

4. Initialize the Chatbot

Use the iServeChatbot widget to integrate the chatbot into your application.

import 'package:flutter/material.dart';
import 'package:iserve_chatbot/iserve_chatbot.dart';

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>',
        ),
        chatApiCredentials: const ChatbotApiCredentials(
          baseUrl: 'https://your-api.example.com',
          messageEndpoint: '/chat/message',
          optionEndpoint: '/chat/options',
          sessionEndpoint: '/chat/session',
          threadsEndpoint: '/chat/threads',
        ),
      ),
    );
  }
}

The package handles the following internally:

  • Preference initialization
  • BLoC creation and state management
  • Repository configuration
  • Session restoration
  • Chatbot UI rendering

You do not need to create a separate ChatbotBloc or ChatbotRepository in the consuming application.

Widget Configuration

The iServeChatbot widget supports the following parameters:

Parameter Type Required Default Description
key Key? No null Standard Flutter widget key
user ChatbotUser Yes — User and organization context
theme IserveChatbotTheme No const IserveChatbotTheme() Customizes the chatbot appearance
chatApiCredentials ChatbotApiCredentials Yes — API base URL and endpoint configuration
showChatHistoryMenu bool No false Controls chat history menu visibility

Display the Chat History Menu

The chat history menu is disabled by default. Set showChatHistoryMenu to true to enable it.

iServeChatbot(
  user: chatbotUser,
  chatApiCredentials: chatbotApiCredentials,
  showChatHistoryMenu: true,
)

When enabled, the chatbot UI can display its chat history menu, depending on the history functionality implemented in the package and supported by the backend.

Session Management

The package uses its internal ChatbotPreferences implementation to persist session information using SharedPreferences.

The consuming application does not need to initialize ChatbotPreferences manually.

Session Initialization Flow

When iServeChatbot is created:

  1. The package initializes ChatbotPreferences.
  2. It retrieves the previously stored session ID.
  3. If a non-empty session ID exists, the package creates its internal ChatbotBloc and dispatches GetChatSession.
  4. If no session ID exists, the chatbot opens without automatically requesting an existing session.
  5. The chatbot UI is rendered after preference initialization completes.

A loading indicator is displayed while preference initialization is in progress.

Session Persistence

Session information is stored internally so the chatbot can attempt to restore a previous conversation when initialized again.

The exact persistence and restoration behavior depends on the implementation of ChatbotPreferences, ChatbotBloc, and the configured backend.

Session API Configuration

The session endpoint is configured through ChatbotApiCredentials.

For example, a backend may expect a session request in the following format:

https://your-api.example.com/chat/session/<session-id>

The actual URL structure depends on how the repository constructs the request and how the backend defines its session API.

Custom Theme

Customize the chatbot appearance using IserveChatbotTheme.

iServeChatbot(
  user: chatbotUser,
  chatApiCredentials: chatbotApiCredentials,
  theme: const IserveChatbotTheme(
    backgroundColor: Colors.white,
    botBubbleColor: Color(0xFFF1F3F5),
    userBubbleColor: Color(0xFF1976D2),
    botTextColor: Colors.black87,
    userTextColor: Colors.white,
    sendButtonColor: Color(0xFF1976D2),
  ),
)

Import Flutter's Material library when using Colors or Color.

The theme can customize the available UI elements, including:

  • Chat background and header
  • Header text and colors
  • Drawer background and text
  • Bot and user message bubbles
  • Message text colors
  • Interactive option buttons
  • Input field and send button
  • Knowledge-base result cards
  • Error messages
  • Border radius and padding

The example assumes these fields are available in your current IserveChatbotTheme implementation. If the theme constructor differs, use the properties exposed by your package version.

Architecture

The package follows a layered architecture that separates the public integration API, UI, state management, preferences, and API communication.

iserve_chatbot/
├── iServeChatbot
│   └── Public integration widget
├── ChatbotView
│   └── Chatbot user interface
├── ChatbotBloc
│   └── State management and conversation flow
├── ChatbotRepository
│   └── API communication
├── ChatbotPreferences
│   └── Session persistence
├── ChatbotApiCredentials
│   └── Configurable API endpoints
├── ChatbotUser
│   └── User and organization context
└── IserveChatbotTheme
    └── UI customization

Architecture Responsibilities

  • iServeChatbot: Initializes preferences and configures the chatbot widget.
  • ChatbotView: Renders the chatbot interface.
  • ChatbotBloc: Handles chatbot events and state transitions.
  • ChatbotRepository: Communicates with the chatbot backend.
  • ChatbotPreferences: Persists session information.
  • ChatbotApiCredentials: Provides the API base URL and endpoint paths.
  • ChatbotUser: Supplies user and organization context.
  • IserveChatbotTheme: Defines the chatbot's visual appearance.

The BLoC, repository, preferences, and internal widgets are implementation details. Applications should generally interact with the package through its public API.

Project Structure

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

Example Application

The package includes an example application demonstrating chatbot integration.

Run it using:

cd example
flutter pub get
flutter run

Update the example's API URL, endpoint paths, and user details to match your backend configuration.

Requirements

  • Flutter SDK compatible with the package's declared Flutter SDK constraint.
  • Dart SDK >=3.10.1 <4.0.0, provided this matches the SDK constraint declared in pubspec.yaml.
  • A chatbot backend exposing the configured API endpoints.
  • Network access to the configured backend.

Versioning

This package follows Semantic Versioning.

Change Example
Bug fix 0.1.0 → 0.1.1
Backward-compatible feature 0.1.1 → 0.2.0
Breaking change 0.2.0 → 1.0.0

Release notes are maintained in CHANGELOG.md.

License

See the LICENSE file for license information.

Contributing

Contributions, issues, and feature requests are welcome. Please follow the project's development guidelines when submitting changes.

Libraries

iserve_chatbot