> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-audit-mechanical-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Additional Message Filtering

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

<Accordion title="AI Integration Quick Reference">
  ```dart theme={null}
  // 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`
</Accordion>

The `MessagesRequest` class helps you fetch messages based on various parameters — returning [`BaseMessage`](/sdk/reference/messages#basemessage) objects that can be [`TextMessage`](/sdk/reference/messages#textmessage), [`MediaMessage`](/sdk/reference/messages#mediamessage), [`CustomMessage`](/sdk/reference/messages#custommessage), [`Action`](/sdk/reference/messages#action), or [`Call`](/sdk/reference/messages#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`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..limit = 30).build();
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";
    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String GUID = "cometchat-uid-1";
    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..guid = GUID
              ..limit = 50).build();   
    ```
  </Tab>
</Tabs>

<Note>
  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`.
</Note>

## 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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..messageId = 50
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..timestamp = DateTime.now()
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..unread = true
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

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`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..hideMessagesFromBlockedUsers = true
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..updatedAfter = DateTime.now()
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

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`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..updatedAfter = DateTime.now()
              ..updatesOnly = true
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

## 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](/sdk/flutter/v4/message-structure-and-hierarchy) to get familiar with the various categories of messages.

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";
    List<String> categories = [];
    categories.add("message");
    categories.add("custom");

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..categories = categories
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

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](/sdk/flutter/v4/message-structure-and-hierarchy) 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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";
    List<String> types = [];
    types.add("image");
    types.add("video");

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..types = types
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..parentMessageId = 103
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

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`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..hideReplies = true
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

## 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`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..hideDeleted = true
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

## 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`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..hideQuotedMessages = true
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";
    List<String> tags  = [];
    tags.add("tag1");
    tags.add("tag2");

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..tags = tags
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

## 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`.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
              ..uid = UID
              ..withTags = true
              ..limit = 50).build();
    ```
  </Tab>
</Tabs>

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`.

<Note>
  This feature is only available with `Conversation & Advanced Search`. The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](https://www.cometchat.com/pricing). If you're already on one of these plans, please enable the `Conversation & Advanced Search` from [CometChat Dashboard](https://app.cometchat.com) (Open your app, navigate to Chats -> Settings -> General Configuration)
</Note>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
      ..uid = UID
      ..hasLinks = true
      ..limit = 50).build();
    ```
  </Tab>
</Tabs>

## 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`.

<Note>
  This feature is only available with `Conversation & Advanced Search`. The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](https://www.cometchat.com/pricing). If you're already on one of these plans, please enable the `Conversation & Advanced Search` from [CometChat Dashboard](https://app.cometchat.com) (Open your app, navigate to Chats -> Settings -> General Configuration)
</Note>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
      ..uid = UID
      ..hasAttachments = true
      ..limit = 50).build();
    ```
  </Tab>
</Tabs>

## 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`.

<Note>
  This feature is only available with `Conversation & Advanced Search`. The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](https://www.cometchat.com/pricing). If you're already on one of these plans, please enable the `Conversation & Advanced Search` from [CometChat Dashboard](https://app.cometchat.com) (Open your app, navigate to Chats -> Settings -> General Configuration)
</Note>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
      ..uid = UID
      ..hasReactions = true
      ..limit = 50).build();
    ```
  </Tab>
</Tabs>

## 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`.

<Note>
  This feature is only available with `Conversation & Advanced Search`. The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](https://www.cometchat.com/pricing). If you're already on one of these plans, please enable the `Conversation & Advanced Search` from [CometChat Dashboard](https://app.cometchat.com) (Open your app, navigate to Chats -> Settings -> General Configuration)
</Note>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
      ..uid = UID
      ..hasMentions = true
      ..limit = 50).build();
    ```
  </Tab>
</Tabs>

## 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.

<Note>
  This feature is only available with `Conversation & Advanced Search`. The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](https://www.cometchat.com/pricing). If you're already on one of these plans, please enable the `Conversation & Advanced Search` from [CometChat Dashboard](https://app.cometchat.com) (Open your app, navigate to Chats -> Settings -> General Configuration)
</Note>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";
    List<String> mentionedUIDs = [];
    mentionedUIDs.add("cometchat-uid-1");
    MessagesRequest messageRequest = (MessagesRequestBuilder()
      ..uid = UID
      ..mentionedUids = mentionedUIDs
      ..limit = 50).build();
    ```
  </Tab>
</Tabs>

## 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.

<Note>
  This feature is only available with `Conversation & Advanced Search`. The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](https://www.cometchat.com/pricing). If you're already on one of these plans, please enable the `Conversation & Advanced Search` from [CometChat Dashboard](https://app.cometchat.com) (Open your app, navigate to Chats -> Settings -> General Configuration)
</Note>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String UID = "cometchat-uid-1";

    MessagesRequest messageRequest = (MessagesRequestBuilder()
      ..uid = UID
      ..attachmentTypes = ["image", "video"]
      ..limit = 50).build();
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Receive Messages" icon="inbox" href="/sdk/flutter/receive-messages">
    Handle incoming messages in real-time with listeners
  </Card>

  <Card title="Retrieve Conversations" icon="comments" href="/sdk/flutter/retrieve-conversations">
    Fetch and display conversation lists with filtering options
  </Card>

  <Card title="Message Structure" icon="sitemap" href="/sdk/flutter/message-structure-and-hierarchy">
    Understand message categories, types, and hierarchy
  </Card>

  <Card title="Threaded Messages" icon="layer-group" href="/sdk/flutter/threaded-messages">
    Work with message threads and replies
  </Card>
</CardGroup>