Additional Message Filtering

Advanced filtering options for fetching messages using MessagesRequestBuilder in the CometChat Flutter SDK.

AI Integration Quick Reference

// Basic message request for user conversation
MessagesRequest request = (MessagesRequestBuilder()
  ..uid = "user_uid"
  ..limit = 30
).build();

// Fetch messages for group with filters
MessagesRequest request = (MessagesRequestBuilder()
  ..guid = "group_guid"
  ..limit = 50
  ..categories = ["message", "custom"]
  ..types = ["text", "image"]
  ..hideReplies = true
).build();

// Unread messages only
MessagesRequest request = (MessagesRequestBuilder()
  ..uid = "user_uid"
  ..unread = true
  ..limit = 50
).build();

// Paginate through messages
List<BaseMessage> messages = await request.fetchPrevious();
List<BaseMessage> moreMessages = await request.fetchPrevious(); // Next page

Key properties: uid, guid, limit, categories, types, tags, unread, parentMessageId, messageId, timestamp, hideReplies, hideDeleted, hideQuotedMessages, searchKeyword, updatedAfter, updatesOnly, hideMessagesFromBlockedUsers, withTags, hasMentions, hasLinks, hasAttachments, hasReactions, mentionedUids, attachmentTypes, withParent

The MessagesRequest class helps you fetch messages based on various parameters — returning BaseMessage objects that can be TextMessage, MediaMessage, CustomMessage, Action, or Call. It uses the Builder design pattern via MessagesRequestBuilder.

To fetch messages:

1. Create a MessagesRequestBuilder object
2. Set your desired parameters
3. Call build() to get a MessagesRequest object
4. Call fetchNext() or fetchPrevious() to retrieve messages

Method	Description
fetchNext()	Returns messages after the specified parameters
fetchPrevious()	Returns messages before the specified parameters

Messages are paginated with a maximum of 100 per request. Calling fetchPrevious()/fetchNext() repeatedly on the same object gets subsequent pages.

MessagesRequestBuilder Parameters

Parameter	Type	Description
uid	String?	User ID to fetch conversation messages for
guid	String?	Group ID to fetch conversation messages for
limit	int?	Number of messages per request (max 100, default 30)
messageId	int?	Fetch messages before/after this message ID
timestamp	DateTime?	Fetch messages before/after this timestamp
unread	bool?	Fetch only unread messages
hideMessagesFromBlockedUsers	bool?	Exclude messages from blocked users (default false)
searchKeyword	String?	Search keyword to filter messages
updatedAfter	DateTime?	Fetch messages updated/received after this time
updatesOnly	bool?	Fetch only updated messages (use with updatedAfter)
category	String?	Single message category filter
type	String?	Single message type filter
parentMessageId	int?	Fetch messages in a specific thread
hideReplies	bool?	Exclude threaded messages (default false)
hideDeleted	bool?	Exclude deleted messages (default false)
categories	List<String>?	Filter by multiple message categories
types	List<String>?	Filter by multiple message types
withTags	bool?	Include tag information in response (default false)
tags	List<String>?	Filter by specific tags
hasMentions	bool?	Fetch only messages with mentions (default false)
hasLinks	bool?	Fetch only messages with links (default false)
hasAttachments	bool?	Fetch only messages with attachments (default false)
hasReactions	bool?	Fetch only messages with reactions (default false)
mentionedUids	List<String>?	Fetch messages mentioning specific users
attachmentTypes	List<String>?	Filter by specific attachment types
interactionGoalCompletedOnly	bool?	Fetch only messages with completed interaction goals (default false)
withParent	bool?	Include parent message with replies (default false)
hideQuotedMessages	bool?	Exclude quoted messages (default false)

Number of messages fetched

In other words, how do I set the number of messages fetched in a single iteration

To achieve this, you can use the limit property. This takes an integer value and informs the SDK to fetch the specified number of messages in one iteration. The maximum number of messages that can be fetched in one go is 100.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..limit = 30).build();

Messages for a user conversation

In other words, how do I fetch messages between me and any user

Use the uid property to fetch messages between the logged-in user and a specific user.

Dart

String UID = "cometchat-uid-1";
MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..limit = 50).build();

Messages for a group conversation

In other words, how do I fetch messages for any group conversation

Use the guid property to fetch messages from a group. The logged-in user must be a member of the group.

Dart

String GUID = "cometchat-uid-1";
MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..guid = GUID
          ..limit = 50).build();   

If neither uid nor guid is set, all messages for the logged-in user across all conversations will be fetched. All parameters below can be combined with uid or guid.

Messages before/after a message

In other words, how do I fetch messages before or after a particular message

Use the messageId property. This provides messages only after/before the message-id based on if fetchNext() or fetchPrevious() is called.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..messageId = 50
          ..limit = 50).build();

This property can be used along with uid or guid to fetch messages after/before any specific message-id for a particular user/group conversation.

Messages before/after a given time

In other words, how do I fetch messages before or after a particular date or time

Use the timestamp property. This takes a DateTime value and provides messages only after/before the timestamp based on if fetchNext() or fetchPrevious() is called.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..timestamp = DateTime.now()
          ..limit = 50).build();

This property can be used along with uid or guid to fetch messages after/before any specific date or time for a particular user/group conversation.

Unread messages

In other words, how do I fetch unread messages

Use the unread property set to true to return just the unread messages.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..unread = true
          ..limit = 50).build();

Combine with guid or uid to fetch unread messages for a specific conversation.

Exclude messages from blocked users

In other words, how do I fetch messages excluding the messages from the users I have blocked

Use the hideMessagesFromBlockedUsers property. If set to true, messages from users blocked by the logged-in user will be excluded. Default is false.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..hideMessagesFromBlockedUsers = true
          ..limit = 50).build();

This also works in group conversations where both users are members.

Updated and received messages

In other words, how do I fetch messages that have been received or updated after a particular date or time

Use the updatedAfter property with a DateTime value to return all messages that have been updated and the ones that have been sent/received after the specified time. Updated messages include those marked as read/delivered, edited, or deleted.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..updatedAfter = DateTime.now()
          ..limit = 50).build();

Useful for syncing messages with a local database — fetch only what’s changed since your last sync.

Updated messages only

In other words, how do I fetch messages that have been updated after a particular date or time

Use the updatesOnly property set to true together with updatedAfter to get just the updated messages and not the messages sent/received after the specified time. This property must be used with updatedAfter.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..updatedAfter = DateTime.now()
          ..updatesOnly = true
          ..limit = 50).build();

Messages for multiple categories

In other words, how do I fetch messages belonging to multiple categories

We recommend before trying this, you refer to the Message structure and hierarchy guide to get familiar with the various categories of messages.

Use the categories property with a list of category names to filter by message category.

Dart

String UID = "cometchat-uid-1";
List<String> categories = [];
categories.add("message");
categories.add("custom");

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..categories = categories
          ..limit = 50).build();

The above snippet will help you get only the messages belonging to the message and custom category. This can also be used to disable certain categories of messages like call and action. This along with uid and guid can help display only the messages you wish to display avoiding the other category of messages.

Messages for multiple types

In other words, how do I fetch messages belonging to multiple types

We recommend you refer to the Message structure and hierarchy guide to get familiar with the various types of messages before trying this out.

Use the types property with a list of type names to filter by message type.

Dart

String UID = "cometchat-uid-1";
List<String> types = [];
types.add("image");
types.add("video");

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..types = types
          ..limit = 50).build();

Using the above code snippet, you can fetch all the media messages. This along with uid or guid can be used to fetch media messages for any particular conversation. This can be useful in many other scenarios as well.

Messages for a specific thread

In other words, how do I fetch messages that are a part of a thread and not directly a user/group conversations

Use the parentMessageId property when you have implemented threaded conversations. This will return only messages belonging to the thread with the specified parent ID.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..parentMessageId = 103
          ..limit = 50).build();

The above code snippet returns the messages that belong to the thread with parent id 103.

Hide threaded messages in user/group conversations

In other words, how do I exclude threaded messages from the normal user/group conversations

Use the hideReplies property set to true to exclude messages that belong to threads. Default is false.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..hideReplies = true
          ..limit = 50).build();

Hide deleted messages in user/group conversations

In other words, how do I exclude deleted messages a user/group conversations

Use the hideDeleted property set to true to exclude deleted messages. Default is false.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..hideDeleted = true
          ..limit = 50).build();

Hide quoted messages in user/group conversations

In other words, how do I exclude quoted messages from user/group conversations

Use the hideQuotedMessages property set to true to exclude quoted messages. Default is false.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..hideQuotedMessages = true
          ..limit = 50).build();

Messages by tags

In other words, how do I fetch messages belonging to specific tags

Use the tags property with a list of tag names to fetch only messages with those tags.

Dart

String UID = "cometchat-uid-1";
List<String> tags  = [];
tags.add("tag1");
tags.add("tag2");

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..tags = tags
          ..limit = 50).build();

Messages with tags

In other words, how do I fetch messages with the tags information

Use the withTags property set to true to include tag information in the response. Default is false.

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
          ..uid = UID
          ..withTags = true
          ..limit = 50).build();

When withTags is set to true, each message’s tags field will be populated.

Additional Field	Type	Description
tags	List<String>	Tags associated with the message

Messages with links

In other words, as a logged-in user, how do I fetch messages that contain links?

Use the hasLinks property set to true to fetch only messages containing links. Default is false.

This feature is only available with Conversation & Advanced Search. The Conversation & Advanced Search is only available in Advanced & Custom plans. If you’re already on one of these plans, please enable the Conversation & Advanced Search from CometChat Dashboard (Open your app, navigate to Chats -> Settings -> General Configuration)

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
  ..uid = UID
  ..hasLinks = true
  ..limit = 50).build();

Messages with attachments

In other words, as a logged-in user, how do I fetch messages that contain attachments?

Use the hasAttachments property set to true to fetch only messages with attachments (image, audio, video, or file). Default is false.

This feature is only available with Conversation & Advanced Search. The Conversation & Advanced Search is only available in Advanced & Custom plans. If you’re already on one of these plans, please enable the Conversation & Advanced Search from CometChat Dashboard (Open your app, navigate to Chats -> Settings -> General Configuration)

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
  ..uid = UID
  ..hasAttachments = true
  ..limit = 50).build();

Messages with reactions

In other words, as a logged-in user, how do I fetch messages that contain reactions?

Use the hasReactions property set to true to fetch only messages with reactions. Default is false.

This feature is only available with Conversation & Advanced Search. The Conversation & Advanced Search is only available in Advanced & Custom plans. If you’re already on one of these plans, please enable the Conversation & Advanced Search from CometChat Dashboard (Open your app, navigate to Chats -> Settings -> General Configuration)

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
  ..uid = UID
  ..hasReactions = true
  ..limit = 50).build();

Messages with mentions

In other words, as a logged-in user, how do I fetch messages that contain mentions?

Use the hasMentions property set to true to fetch only messages with mentions. Default is false.

This feature is only available with Conversation & Advanced Search. The Conversation & Advanced Search is only available in Advanced & Custom plans. If you’re already on one of these plans, please enable the Conversation & Advanced Search from CometChat Dashboard (Open your app, navigate to Chats -> Settings -> General Configuration)

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
  ..uid = UID
  ..hasMentions = true
  ..limit = 50).build();

Messages with particular user mentions

In other words, as a logged-in user, how do I fetch messages that mention specific users?

Use the mentionedUids property with a list of UIDs to fetch messages that mention specific users.

This feature is only available with Conversation & Advanced Search. The Conversation & Advanced Search is only available in Advanced & Custom plans. If you’re already on one of these plans, please enable the Conversation & Advanced Search from CometChat Dashboard (Open your app, navigate to Chats -> Settings -> General Configuration)

Dart

String UID = "cometchat-uid-1";
List<String> mentionedUIDs = [];
mentionedUIDs.add("cometchat-uid-1");
MessagesRequest messageRequest = (MessagesRequestBuilder()
  ..uid = UID
  ..mentionedUids = mentionedUIDs
  ..limit = 50).build();

Messages with specific attachment types

In other words, as a logged-in user, how do I fetch messages with specific types of attachments?

Use the attachmentTypes property with a list of attachment type values to fetch messages with specific attachment types.

This feature is only available with Conversation & Advanced Search. The Conversation & Advanced Search is only available in Advanced & Custom plans. If you’re already on one of these plans, please enable the Conversation & Advanced Search from CometChat Dashboard (Open your app, navigate to Chats -> Settings -> General Configuration)

Dart

String UID = "cometchat-uid-1";

MessagesRequest messageRequest = (MessagesRequestBuilder()
  ..uid = UID
  ..attachmentTypes = ["image", "video"]
  ..limit = 50).build();

---

Next Steps

Receive Messages

Handle incoming messages in real-time with listeners

Retrieve Conversations

Fetch and display conversation lists with filtering options

Message Structure

Understand message categories, types, and hierarchy

Threaded Messages

Work with message threads and replies