ai_chat_bot_flutter 1.0.2

A customizable Flutter AI chatbot widget with bottom sheet or full page mode, predefined prompts, and theme support.

AI Chat Bot Flutter 🤖

A modern, customizable Flutter AI chatbot package with OpenRouter integration, local conversation history, predefined responses, and full theme control.

---

✨ Features

• 🤖 AI-powered chatbot using OpenRouter
• 💬 Floating chatbot launcher
• 📱 Two chat display modes:
  • Bottom Sheet
  • Full Page
• ⚡ Predefined quick questions
• 💡 Predefined instant responses
• 🧠 Smart response flow:
  • Predefined messages
  • Predefined buttons
  • AI fallback
• 💾 Local conversation history
• 🗑️ Clear chat history support
• 🔄 Automatically restores previous messages
• 🧩 Optional custom storage key
• 🎨 Modern default UI
• 🎨 Fully customizable colors
• 🖼️ Fully customizable icons
• ✏️ Customizable chatbot labels and messages
• 🕒 Optional message timestamps
• 🟢 Optional assistant status indicator
• 📦 Configurable maximum stored messages
• 🧩 Easy integration into existing Flutter applications

---

📸 Preview

---

🚀 Installation

Add the package to your pubspec.yaml:

dependencies:
  ai_chat_bot_flutter: ^1.0.2

Then run:

flutter pub get

---

📦 Import

import 'package:ai_chat_bot_flutter/ai_chat_bot_flutter.dart';

---

🔐 OpenRouter API Token

This package uses OpenRouter to generate AI responses.

Step 1 — Create an OpenRouter account

Visit:

https://openrouter.ai/

Step 2 — Create an API key

1. Open your OpenRouter dashboard.
2. Go to API Keys.
3. Select Create New Key.
4. Copy your generated API key.

⚠️ Never commit your API key to a public GitHub repository.

For production applications, using a backend service to protect your API credentials is recommended.

---

💾 Initialize Local Chat Storage

Version 1.0.2 supports persistent local conversation history.

Initialize the chatbot database before runApp():

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await ChatBotLocalDatabase.init();

  runApp(const MyApp());
}

The chatbot can now automatically save and restore conversations on the device.

---

⚡ Quick Start

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

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await ChatBotLocalDatabase.init();

  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'AI Chat Bot Example',
      theme: ThemeData(
        useMaterial3: true,
        colorScheme: ColorScheme.fromSeed(
          seedColor: Colors.blue,
        ),
      ),
      home: const HomePage(),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('AI Chat Bot'),
      ),
      body: Stack(
        children: [
          const Center(
            child: Text(
              'Tap the chat button to get started.',
            ),
          ),

          SmartChatBotHelper(
            appName: 'Facebook',

            appDescription:
                'Facebook is a social app where users can connect with '
                'friends, chat, share posts, photos, and videos.',

            token: yourOpenRouterToken,

            predefinedMessages: const {
              'hi':
                  'Hi 👋 Welcome! How can I help you today?',

              'who are you':
                  'I’m your assistant 🤖, here to help you use the app.',
            },

            predefinedButtons: const {
              'How do I create a post?':
                  "Tap 'What's on your mind?' to create a new post.",

              'How do I add a friend?':
                  "Open a user's profile and tap 'Add Friend'.",

              'How do I send a message?':
                  'Open Messenger, select a friend, and start chatting.',

              'How do I upload a photo?':
                  "Tap 'Photo/Video' while creating a post.",

              'How do I see notifications?':
                  'Tap the bell icon to view your notifications.',
            },
          ),
        ],
      ),
    );
  }
}

That's all you need to get started.

---

🧠 How Responses Work

The chatbot follows this response flow:

1. The user sends a message.
2. The chatbot checks predefinedMessages.
3. If a matching predefined message is found, it returns the predefined response immediately.
4. If the message was triggered from a predefined button, it uses the configured predefined button response.
5. Otherwise, the message is sent to OpenRouter.
6. The AI response is displayed to the user.
7. The conversation is saved locally when persistence is enabled.

This allows common questions to be answered instantly without using an AI request.

---

⚡ Predefined Messages

Use predefinedMessages for greetings or common messages:

predefinedMessages: const {
  'hi':
      'Hi 👋 How can I help you today?',

  'hello':
      'Hello! Welcome to the app.',

  'who are you':
      'I’m your AI assistant.',
},

These responses do not require an OpenRouter request.

---

💡 Predefined Quick Questions

Use predefinedButtons to show common questions:

predefinedButtons: const {
  'How do I create an account?':
      'Open the registration page and enter your information.',

  'How do I update my profile?':
      'Open Profile and select Edit Profile.',

  'How do I contact support?':
      'Open Help & Support from the settings page.',
},

Users can select a question instead of typing it manually.

---

📱 Chat Opening Modes

The chatbot supports two display modes.

Bottom Sheet

This is the default:

openType: ChatBotOpenType.bottomSheet,

The chatbot opens as a modal bottom sheet.

Full Page

openType: ChatBotOpenType.page,

The chatbot opens as a full-screen page.

Example:

SmartChatBotHelper(
  appName: 'My App',
  appDescription: 'Description of my application.',
  token: yourOpenRouterToken,

  openType: ChatBotOpenType.page,

  predefinedMessages: const {},
  predefinedButtons: const {},
),

---

💾 Local Conversation History

Conversation persistence is enabled by default:

persistMessages: true,

Messages are stored locally on the user's device.

When the chatbot is opened again, previous messages are automatically restored.

Example:

SmartChatBotHelper(
  appName: 'My App',
  appDescription: 'My application description.',
  token: yourOpenRouterToken,

  persistMessages: true,

  predefinedMessages: const {},
  predefinedButtons: const {},
),

To disable local history:

persistMessages: false,

---

🔑 Custom Storage Key

Normally, you do not need to provide a storage key.

The package automatically generates one using appName.

For example:

appName: 'My App'

automatically creates a storage key similar to:

ai_chat_bot_my_app

If your application supports multiple accounts or multiple chatbot instances, you can provide your own key:

storageKey: 'support_${user.id}',

Example:

SmartChatBotHelper(
  appName: 'Support',
  appDescription: 'Customer support assistant.',
  token: yourOpenRouterToken,

  storageKey: 'support_user_123',

  predefinedMessages: const {},
  predefinedButtons: const {},
),

---

📦 Maximum Stored Messages

You can prevent local chat history from growing indefinitely.

Default:

maxStoredMessages: 200,

Example:

SmartChatBotHelper(
  appName: 'My App',
  appDescription: 'My application.',
  token: yourOpenRouterToken,

  maxStoredMessages: 100,

  predefinedMessages: const {},
  predefinedButtons: const {},
),

Only the latest configured number of messages will be retained.

---

🗑️ Clear Conversation History

The chatbot can display a clear-history button:

showClearHistoryButton: true,

Users will receive a confirmation dialog before their history is removed.

You can also clear conversation history programmatically:

await ChatBotLocalDatabase.clearConversation(
  'your_storage_key',
);

To delete every chatbot conversation stored by the package:

await ChatBotLocalDatabase.clearAll();

---

🎨 Theme Customization

The package includes a modern default design.

You do not need to configure a theme unless you want to match your application's branding.

Example:

SmartChatBotHelper(
  appName: 'My App',
  appDescription: 'My application description.',
  token: yourOpenRouterToken,

  predefinedMessages: const {},
  predefinedButtons: const {},

  theme: const ChatBotTheme(
    primaryColor: Colors.green,

    backgroundColor: Color(0xFFF8FAFC),
    surfaceColor: Colors.white,

    userMessageColor: Colors.green,
    userMessageTextColor: Colors.white,

    botMessageColor: Colors.white,
    botMessageTextColor: Color(0xFF1E293B),

    sendButtonColor: Colors.green,

    launcherBackgroundColor: Colors.green,
    launcherIconColor: Colors.white,
  ),
),

---

🖼️ Icon Customization

Chatbot icons can also be customized.

theme: const ChatBotTheme(
  launcherIcon: Icons.chat_rounded,
  botIcon: Icons.support_agent_rounded,
  sendIcon: Icons.send_rounded,

  backIcon: Icons.arrow_back_rounded,
  closeIcon: Icons.close_rounded,

  clearHistoryIcon:
      Icons.delete_outline_rounded,

  suggestionIcon:
      Icons.lightbulb_outline_rounded,
),

---

✏️ Text Customization

Visible chatbot labels can be customized using ChatBotStrings.

SmartChatBotHelper(
  appName: 'My App',
  appDescription: 'My application.',
  token: yourOpenRouterToken,

  predefinedMessages: const {},
  predefinedButtons: const {},

  strings: const ChatBotStrings(
    headerTitle: 'My AI Assistant',

    headerStatus:
        'Ready to help',

    inputHint:
        'Ask me anything...',

    suggestionsTitle:
        'You can ask',

    thinkingText:
        'Thinking...',

    launcherTooltip:
        'Open Assistant',

    clearHistoryTitle:
        'Delete conversation?',

    clearHistoryMessage:
        'Your local chat history will be permanently removed.',

    clearHistoryCancel:
        'Keep',

    clearHistoryConfirm:
        'Delete',

    welcomeMessage:
        'Hi 👋 How can I help you today?',
  ),
),

---

🕒 Message Timestamps

Timestamps can be shown or hidden:

showMessageTimestamp: true,

Disable them with:

showMessageTimestamp: false,

---

🟢 Assistant Status

The assistant header can display its status indicator.

showStatusIndicator: true,

To hide it:

showStatusIndicator: false,

The status text can be customized:

strings: const ChatBotStrings(
  headerStatus: 'Available',
),

---

💬 Predefined Questions Style

Predefined questions can appear as regular horizontal quick actions:

showPredefinedAsChatMessages: false,

Or inside the chat interface:

showPredefinedAsChatMessages: true,

---

⚙️ SmartChatBotHelper Configuration

Parameter	Type	Required	Default	Description
appName	String	✅	—	Application/assistant name
appDescription	String	✅	—	Context provided to the AI
token	String	✅	—	OpenRouter API token
predefinedMessages	Map<String, String>	✅	—	Instant predefined responses
predefinedButtons	Map<String, String>	✅	—	Suggested quick questions
theme	ChatBotTheme?	❌	Default theme	Chatbot appearance
strings	ChatBotStrings	❌	Default strings	Visible chatbot labels
openType	ChatBotOpenType	❌	bottomSheet	Chat opening mode
showPredefinedAsChatMessages	bool	❌	false	Show predefined questions inside chat
showMessageTimestamp	bool	❌	true	Show message timestamps
showStatusIndicator	bool	❌	true	Show assistant status
persistMessages	bool	❌	true	Save conversations locally
storageKey	String?	❌	Auto-generated	Custom local storage key
showClearHistoryButton	bool	❌	true	Show clear conversation action
maxStoredMessages	int	❌	200	Maximum locally stored messages

---

🎨 Main ChatBotTheme Options

General

Property	Description
primaryColor	Primary chatbot brand color
backgroundColor	Main chat background
surfaceColor	Surface/card background
textPrimaryColor	Main text color
textSecondaryColor	Secondary text color
dividerColor	Divider color
shadowColor	Shadow color

Messages

Property	Description
userMessageColor	User bubble background
userMessageTextColor	User message text
botMessageColor	Assistant bubble background
botMessageTextColor	Assistant message text
userTimestampTextColor	User timestamp color
botTimestampTextColor	Bot timestamp color
messageBubbleRadius	Bubble corner radius

Input

Property	Description
inputBackgroundColor	Input background
inputBorderColor	Input border
inputTextColor	Input text
inputHintColor	Input placeholder
sendButtonColor	Send button background
sendButtonIconColor	Send icon color
sendIcon	Send button icon

Header

Property	Description
headerBackgroundColor	Header background
headerIconColor	Header action icon color
botAvatarBackgroundColor	Assistant avatar background
botAvatarIconColor	Assistant avatar icon
onlineIndicatorColor	Status indicator
botIcon	Assistant icon

Launcher

Property	Description
launcherBackgroundColor	Floating launcher background
launcherIconColor	Launcher icon color
launcherIcon	Launcher icon
launcherSize	Launcher button size
launcherRadius	Launcher border radius
launcherElevation	Launcher shadow elevation
launcherBottom	Distance from bottom
launcherRight	Distance from right

Suggestions

Property	Description
predefinedButtonColor	Suggestion background
predefinedButtonTextColor	Suggestion text
predefinedButtonBorderColor	Suggestion border
predefinedButtonRadius	Suggestion radius
suggestionIcon	Suggestions section icon

---

🧩 Complete Configuration Example

SmartChatBotHelper(
  appName: 'My App',

  appDescription:
      'My App helps users manage their daily activities.',

  token: yourOpenRouterToken,

  openType:
      ChatBotOpenType.page,

  persistMessages: true,

  maxStoredMessages: 200,

  showClearHistoryButton: true,

  showMessageTimestamp: true,

  showStatusIndicator: true,

  showPredefinedAsChatMessages: true,

  predefinedMessages: const {
    'hi':
        'Hello 👋 How can I help you?',
  },

  predefinedButtons: const {
    'How do I get started?':
        'Open the home page and follow the setup instructions.',
  },

  strings: const ChatBotStrings(
    headerTitle: 'My Assistant',
    headerStatus: 'Ready to help',
    inputHint: 'Ask a question...',
    thinkingText: 'Thinking...',
  ),

  theme: const ChatBotTheme(
    primaryColor:
        Color(0xFF16A34A),

    userMessageColor:
        Color(0xFF16A34A),

    sendButtonColor:
        Color(0xFF16A34A),

    launcherBackgroundColor:
        Color(0xFF16A34A),

    launcherIcon:
        Icons.chat_rounded,

    botIcon:
        Icons.support_agent_rounded,

    sendIcon:
        Icons.send_rounded,
  ),
),

---

📂 Local Storage

Local conversation data is stored using hive_ce_flutter.

The data stays on the user's device and belongs to the application using the package.

No server-side conversation database is required.

Local Hive storage is not encrypted by default. If your application handles sensitive conversation data, consider adding encrypted storage appropriate to your application's security requirements.

---

🔐 Security

Never hardcode a production API key in code that will be published publicly.

Avoid:

const token = 'your-real-production-key';

especially in public repositories.

For production applications, consider routing AI requests through your own backend service so the provider API key is not distributed inside the client application.

---

🛠️ Requirements

• Flutter
• Dart ^3.10.4
• OpenRouter API key

The package internally uses:

• http
• hive_ce_flutter

---

🐛 Issues & Contributions

Found a bug or have a feature request?

Open an issue on GitHub:

https://github.com/taufiqelahi/ai_chatbot/issues

Contributions and pull requests are welcome.

---

🔮 Planned Features

Future releases may include:

• 🔊 Voice input and speech-to-text
• 📎 File and image attachments
• 🌐 Multi-language support
• 🧠 Multi-turn AI context improvements
• 📊 Chatbot usage analytics
• 🔌 Multiple AI providers such as OpenAI and Gemini
• 🔐 Optional encrypted local conversation storage
• 🎤 Voice responses / text-to-speech

---

📄 License

This project is licensed under the MIT License.

See the LICENSE file for details.

---

👨‍💻 Author

Taufique A Elahi

GitHub: @taufiqelahi

---

Made with ❤️ for the Flutter community