Additional Message Filtering

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:

Create a MessagesRequestBuilder object
Set your desired parameters
Call build() to get a MessagesRequest object
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.

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.

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.

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.

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.

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

​MessagesRequestBuilder Parameters

​Number of messages fetched

​Messages for a user conversation

​Messages for a group conversation

​Messages before/after a message

​Messages before/after a given time

​Unread messages

​Exclude messages from blocked users

​Updated and received messages

​Updated messages only

​Messages for multiple categories

​Messages for multiple types

​Messages for a specific thread

​Hide threaded messages in user/group conversations

​Hide deleted messages in user/group conversations

​Hide quoted messages in user/group conversations

​Messages by tags

​Messages with tags

​Messages with links

​Messages with attachments

​Messages with reactions

​Messages with mentions

​Messages with particular user mentions

​Messages with specific attachment types

​Next Steps

Receive Messages

Retrieve Conversations

Message Structure

Threaded Messages

MessagesRequestBuilder Parameters

Number of messages fetched

Messages for a user conversation

Messages for a group conversation

Messages before/after a message

Messages before/after a given time

Unread messages

Exclude messages from blocked users

Updated and received messages

Updated messages only

Messages for multiple categories

Messages for multiple types

Messages for a specific thread

Hide threaded messages in user/group conversations

Hide deleted messages in user/group conversations

Hide quoted messages in user/group conversations

Messages by tags

Messages with tags

Messages with links

Messages with attachments

Messages with reactions

Messages with mentions

Messages with particular user mentions

Messages with specific attachment types

Next Steps