AI Assistant Chat History - CometChat Docs

AI Agent Component Spec

{
  "component": "CometChatAIAssistantChatHistory",
  "package": "cometchat_chat_uikit",
  "import": "import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';",
  "description": "A widget that displays the conversation history between users and an AI assistant with date separators and new chat functionality",
  "primaryOutput": {
    "prop": "onMessageClicked",
    "type": "void Function(BaseMessage? message)?"
  },
  "props": {
    "data": {
      "user": {
        "type": "User?",
        "default": "null",
        "note": "User object for user message list (one of user/group required)"
      },
      "group": {
        "type": "Group?",
        "default": "null",
        "note": "Group object for group message list (one of user/group required)"
      },
      "messagesRequestBuilder": {
        "type": "MessagesRequestBuilder?",
        "default": "null",
        "note": "Custom request builder passed to CometChat's SDK"
      }
    },
    "callbacks": {
      "onMessageClicked": "void Function(BaseMessage? message)?",
      "onNewChatButtonClicked": "VoidCallback?",
      "onError": "OnError?",
      "onLoad": "OnLoad<BaseMessage>?",
      "onEmpty": "OnEmpty?",
      "onClose": "VoidCallback?"
    },
    "visibility": {
      "hideStickyDate": {
        "type": "bool?",
        "default": "null"
      },
      "hideDateSeparator": {
        "type": "bool?",
        "default": "null"
      }
    },
    "viewSlots": {
      "loadingStateView": "WidgetBuilder?",
      "emptyStateView": "WidgetBuilder?",
      "errorStateView": "WidgetBuilder?",
      "backButton": "Widget?"
    },
    "formatting": {
      "dateSeparatorPattern": {
        "type": "String Function(DateTime)?",
        "default": "null"
      },
      "dateTimeFormatterCallback": {
        "type": "DateTimeFormatterCallback?",
        "default": "null"
      }
    }
  },
  "events": [],
  "sdkListeners": [],
  "compositionExample": {
    "description": "CometChatAIAssistantChatHistory is typically used within AI assistant features to show past conversations",
    "components": ["CometChatMessageList", "CometChatMessageComposer"],
    "flow": "User opens chat history → Past messages displayed → User clicks message or starts new chat"
  },
  "types": {}
}

Where It Fits

CometChatAIAssistantChatHistory is a pre-built user interface widget designed to display the conversation history between users and an AI assistant within a chat application. It provides a structured and visually appealing way to present past interactions, making it easy for users to review previous messages and context.

Minimal Render

The simplest way to render CometChatAIAssistantChatHistory:

Dart

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

CometChatAIAssistantChatHistory(
  user: user,  // Required: User or Group object
)

Simply adding the CometChatAIAssistantChatHistory component to the layout will only display the loading indicator. To fetch messages for a specific entity, you need to supplement it with User or Group Object.

You can also launch it using Navigator:

Dart

Navigator.push(
  context, 
  MaterialPageRoute(
    builder: (context) => CometChatAIAssistantChatHistory(
      user: user,  // A user or group object is required
    ),
  ),
);

Or embed it as a widget:

Dart

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

class ChatHistory extends StatefulWidget {
  const ChatHistory({super.key});

  @override
  State<ChatHistory> createState() => _ChatHistoryState();
}

class _ChatHistoryState extends State<ChatHistory> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: CometChatAIAssistantChatHistory(
          user: user,  // A user or group object is required
        ),
      ),
    );
  }
}

Filtering

You can adjust the MessagesRequestBuilder to customize the message list. Numerous options are available to alter the builder to meet your specific needs.

Dart

CometChatAIAssistantChatHistory(
  user: user,
  messagesRequestBuilder: MessagesRequestBuilder()
    ..uid = user.uid,
)

The following parameters in messageRequestBuilder will always be altered inside the list:

UID
GUID
types
categories

For additional details on MessagesRequestBuilder, please visit MessagesRequestBuilder.

Actions and Events

Callback Props

Component-level callbacks that fire on specific user interactions:

Callback	Signature	Fires When
`onMessageClicked`	`void Function(BaseMessage? message)?`	User clicks a message
`onNewChatButtonClicked`	`VoidCallback?`	User clicks the new chat button
`onError`	`OnError?`	An error occurs while fetching messages
`onLoad`	`OnLoad<BaseMessage>?`	List is successfully loaded
`onEmpty`	`OnEmpty?`	List is empty
`onClose`	`VoidCallback?`	User clicks the back/close button

Dart

CometChatAIAssistantChatHistory(
  user: user,
  onNewChatButtonClicked: () {
    // Start a new chat session
    print('New chat initiated');
  },
  onMessageClicked: (message) {
    // Navigate to the message context
    print('Message clicked: ${message?.id}');
  },
  onError: (e) {
    print('Error: $e');
  },
  onLoad: (list) {
    print('Messages loaded: ${list.length}');
  },
  onEmpty: () {
    print('No messages found');
  },
  onClose: () {
    Navigator.pop(context);
  },
)

Global UI Events

The CometChatAIAssistantChatHistory component does not produce any global UI events.

Custom View Slots

Customize the appearance of CometChatAIAssistantChatHistory by replacing default views with your own widgets.

Slot	Signature	Replaces
`loadingStateView`	`WidgetBuilder?`	Loading spinner
`emptyStateView`	`WidgetBuilder?`	Empty state display
`errorStateView`	`WidgetBuilder?`	Error state display
`backButton`	`Widget?`	Back/close button

Example: Custom Back Button

Dart

CometChatAIAssistantChatHistory(
  user: user,
  backButton: IconButton(
    icon: const Icon(
      Icons.arrow_back,
      color: Colors.red,
    ),
    onPressed: () {
      Navigator.pop(context);
    },
  ),
)

Example: Custom Loading State

Dart

CometChatAIAssistantChatHistory(
  user: user,
  loadingStateView: (context) {
    return Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          CircularProgressIndicator(),
          SizedBox(height: 16),
          Text('Fetching history...'),
        ],
      ),
    );
  },
)

Example: Custom Empty State

Dart

CometChatAIAssistantChatHistory(
  user: user,
  emptyStateView: (context) {
    return Center(
      child: Text('No history yet. Start a new conversation!'),
    );
  },
)

Date Separator Pattern

You can modify the date pattern of the chat history date separator using dateSeparatorPattern:

Dart

CometChatAIAssistantChatHistory(
  user: user,
  dateSeparatorPattern: (DateTime dateTime) {
    return DateFormat("dd/MM/yyyy").format(dateTime);
  },
)

Styling

Customize the appearance of CometChatAIAssistantChatHistory using CometChatAIAssistantChatHistoryStyle.

Dart

final ccColor = CometChatThemeHelper.getColorPalette(context);

CometChatAIAssistantChatHistory(
  user: user,
  style: CometChatAIAssistantChatHistoryStyle(
    backgroundColor: const Color(0xFFFFFAF6),
    headerBackgroundColor: const Color(0xFFFFFAF6),
    headerTitleTextColor: ccColor.textPrimary,
    headerTitleTextStyle: const TextStyle(
      fontFamily: 'TimesNewRoman',
    ),
    newChatIconColor: ccColor.iconSecondary,
    newChatTextColor: ccColor.textPrimary,
    newChaTitleStyle: const TextStyle(
      fontFamily: 'TimesNewRoman',
    ),
    dateSeparatorStyle: CometChatDateStyle(
      textStyle: const TextStyle(
        fontFamily: 'TimesNewRoman',
      ),
      textColor: ccColor.textTertiary,
      backgroundColor: const Color(0xFFFFFAF6),
    ),
    itemTextStyle: const TextStyle(
      fontFamily: 'TimesNewRoman',
    ),
    itemTextColor: ccColor.textPrimary,
  ),
)

Style Properties

Property	Type	Description
`backgroundColor`	`Color?`	Background color of the message list
`border`	`BoxBorder?`	Border of the message list
`borderRadius`	`BorderRadiusGeometry?`	Border radius of the message list
`emptyStateTextStyle`	`TextStyle?`	Style of empty state text
`emptyStateTextColor`	`Color?`	Color of empty state text
`emptyStateSubtitleStyle`	`TextStyle?`	Style of empty state subtitle
`emptyStateSubtitleColor`	`Color?`	Color of empty state subtitle
`errorStateTextStyle`	`TextStyle?`	Style of error state text
`errorStateTextColor`	`Color?`	Color of error state text
`errorStateSubtitleStyle`	`TextStyle?`	Style of error state subtitle
`errorStateSubtitleColor`	`Color?`	Color of error state subtitle
`dateSeparatorStyle`	`CometChatDateStyle?`	Style for date separator
`newChatIconColor`	`Color?`	Color of new chat icon
`newChaTitleStyle`	`TextStyle?`	Style of new chat title
`newChatTextColor`	`Color?`	Color of new chat text
`itemTextStyle`	`TextStyle?`	Style of item text
`itemTextColor`	`Color?`	Color of item text
`headerBackgroundColor`	`Color?`	Background color of header
`headerTitleTextStyle`	`TextStyle?`	Style of header title text
`headerTitleTextColor`	`Color?`	Color of header title text
`closeIconColor`	`Color?`	Color of close icon
`separatorHeight`	`double?`	Height of separator
`separatorColor`	`Color?`	Color of separator
`deleteChatHistoryDialogStyle`	`CometChatConfirmDialogStyle?`	Style for delete dialog

Props Reference

Prop	Type	Default	Description
`user`	`User?`	`null`	User object for user message list
`group`	`Group?`	`null`	Group object for group message list
`messagesRequestBuilder`	`MessagesRequestBuilder?`	`null`	Custom request builder
`loadingStateView`	`WidgetBuilder?`	`null`	Custom loading view
`emptyStateView`	`WidgetBuilder?`	`null`	Custom empty view
`errorStateView`	`WidgetBuilder?`	`null`	Custom error view
`onMessageClicked`	`void Function(BaseMessage?)?`	`null`	Message click callback
`onError`	`OnError?`	`null`	Error callback
`onLoad`	`OnLoad<BaseMessage>?`	`null`	Load callback
`onEmpty`	`OnEmpty?`	`null`	Empty callback
`onNewChatButtonClicked`	`VoidCallback?`	`null`	New chat button callback
`style`	`CometChatAIAssistantChatHistoryStyle?`	`null`	Style configuration
`dateSeparatorPattern`	`String Function(DateTime)?`	`null`	Date separator pattern
`dateTimeFormatterCallback`	`DateTimeFormatterCallback?`	`null`	Date/time formatter
`emptyStateText`	`String?`	`null`	Empty state text
`emptyStateSubtitleText`	`String?`	`null`	Empty state subtitle
`errorStateText`	`String?`	`null`	Error state text
`errorStateSubtitleText`	`String?`	`null`	Error state subtitle
`onClose`	`VoidCallback?`	`null`	Close callback
`backButton`	`Widget?`	`null`	Custom back button
`width`	`double?`	`null`	Widget width
`height`	`double?`	`null`	Widget height
`hideStickyDate`	`bool?`	`null`	Hide sticky date separator
`hideDateSeparator`	`bool?`	`null`	Hide date separator

Message List

Display messages in a conversation

Message Composer

Compose and send messages

Theming

Learn how to customize the look and feel

Localization

Support multiple languages in your app

​Where It Fits

​Minimal Render

​Filtering

​Actions and Events

​Callback Props

​Global UI Events

​Custom View Slots

​Example: Custom Back Button

​Example: Custom Loading State

​Example: Custom Empty State

​Date Separator Pattern

​Styling

​Style Properties

​Props Reference

Message List

Message Composer

Theming

Localization

Where It Fits

Minimal Render

Filtering

Actions and Events

Callback Props

Global UI Events

Custom View Slots

Example: Custom Back Button

Example: Custom Loading State

Example: Custom Empty State

Date Separator Pattern

Styling

Style Properties

Props Reference