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

# Additional Message Filtering

> Advanced guide to filtering messages using MessagesRequest builder options in the CometChat iOS SDK.

<Info>
  **Quick Reference for AI Agents & Developers**

  * **Filter by type:** `.set(types:)` — e.g., `["text", "image"]`
  * **Filter by category:** `.set(categories:)` — e.g., `["message", "action"]`
  * **Filter by tags:** `.setTags(_:)`, `.withTags(true)`
  * **Filter by sender:** `.set(uid:)` for specific user's messages
  * **Exclude:** `.hideReplies(true)`, `.hideDeletedMessages(true)`
  * **Related:** [Receive Message](/sdk/ios/receive-message) · [Message Structure](/sdk/ios/message-structure-and-hierarchy) · [Messaging Overview](/sdk/ios/messaging-overview)
</Info>

The `MessagesRequest` class as you must be familiar with helps you to fetch messages based on the various parameters provided to it. This document will help you understand better the various options that are available using the `MessagesRequest` class.

***

## Object Structures

For complete object structure definitions, see [Send Message - Object Structures](/sdk/ios/send-message#object-structures):

* [TextMessage Object](/sdk/ios/send-message#textmessage-object)
* [MediaMessage Object](/sdk/ios/send-message#mediamessage-object)
* [CustomMessage Object](/sdk/ios/send-message#custommessage-object)
* [User Object](/sdk/ios/send-message#user-object)
* [Group Object](/sdk/ios/send-message#group-object)
* [CometChatException Object](/sdk/ios/send-message#cometchatexception-object)

***

## 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 `setLimit()` method. This method takes an integer value as the input 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="Swift">
    ```swift theme={null}
    var limit = 50;
    let messagesRequest = MessagesRequest.MessageRequestBuilder()
    .set(limit: limit)
    .build();
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads">
  <Tabs>
    <Tab title="Request">
      **Method:** `MessagesRequest.fetchPrevious()`

      | Parameter | Type  | Value |
      | --------- | ----- | ----- |
      | limit     | `Int` | `30`  |
    </Tab>

    <Tab title="Success Response">
      **Return Type:** `[BaseMessage]` (Array of up to 30 messages)

      **Example [TextMessage](/sdk/ios/send-message#textmessage-object) in array:**

      | Parameter      | Type                     | Value                                    |
      | -------------- | ------------------------ | ---------------------------------------- |
      | id             | `Int`                    | `37790`                                  |
      | muid           | `String`                 | `"1771917000.111111"`                    |
      | conversationId | `String`                 | `"cometchat-uid-2_user_cometchat-uid-3"` |
      | senderUid      | `String`                 | `"cometchat-uid-2"`                      |
      | receiverUid    | `String`                 | `"cometchat-uid-3"`                      |
      | receiverType   | `CometChat.ReceiverType` | `0` (`.user`)                            |
      | messageType    | `CometChat.MessageType`  | `0` (`.text`)                            |
      | sentAt         | `Int`                    | `1771917000`                             |
      | text           | `String`                 | `"Hello!"`                               |

      **sender** ([User](/sdk/ios/send-message#user-object)):

      | Parameter | Type     | Value               |
      | --------- | -------- | ------------------- |
      | uid       | `String` | `"cometchat-uid-2"` |
      | name      | `String` | `"George Alan"`     |
    </Tab>

    <Tab title="Error Response">
      **Object Type:** [CometChatException](/sdk/ios/send-message#cometchatexception-object)

      | Parameter        | Type     | Value                                                     |
      | ---------------- | -------- | --------------------------------------------------------- |
      | errorCode        | `String` | `"ERROR_USER_NOT_LOGGED_IN"`                              |
      | errorDescription | `String` | `"Please log in to CometChat before calling this method"` |
    </Tab>
  </Tabs>
</Accordion>

***

## Messages for a user conversation

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

This can be achieved using the `setUID()` method. This method takes the UID of the user with whom the conversation is to be fetched.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    var limit = 30;
    let messagesRequest = MessagesRequest.MessageRequestBuilder()
    .set(uid: "cometchat-uid-1")
    .set(limit: limit)
    .build();
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads">
  <Tabs>
    <Tab title="Request">
      **Method:** `MessagesRequest.fetchPrevious()`

      | Parameter | Type     | Value               |
      | --------- | -------- | ------------------- |
      | uid       | `String` | `"cometchat-uid-3"` |
      | limit     | `Int`    | `50`                |
    </Tab>

    <Tab title="Success Response">
      **Return Type:** `[BaseMessage]`

      **Example [TextMessage](/sdk/ios/send-message#textmessage-object) in array:**

      | Parameter      | Type                     | Value                                    |
      | -------------- | ------------------------ | ---------------------------------------- |
      | id             | `Int`                    | `37798`                                  |
      | muid           | `String`                 | `"1771917734.123456"`                    |
      | conversationId | `String`                 | `"cometchat-uid-2_user_cometchat-uid-3"` |
      | senderUid      | `String`                 | `"cometchat-uid-2"`                      |
      | receiverUid    | `String`                 | `"cometchat-uid-3"`                      |
      | receiverType   | `CometChat.ReceiverType` | `0` (`.user`)                            |
      | messageType    | `CometChat.MessageType`  | `0` (`.text`)                            |
      | sentAt         | `Int`                    | `1771917734`                             |
      | text           | `String`                 | `"Hello"`                                |

      **sender** ([User](/sdk/ios/send-message#user-object)):

      | Parameter | Type     | Value                                                                   |
      | --------- | -------- | ----------------------------------------------------------------------- |
      | uid       | `String` | `"cometchat-uid-2"`                                                     |
      | name      | `String` | `"George Alan"`                                                         |
      | avatar    | `String` | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"` |

      **receiver** ([User](/sdk/ios/send-message#user-object)):

      | Parameter | Type     | Value                                                                   |
      | --------- | -------- | ----------------------------------------------------------------------- |
      | uid       | `String` | `"cometchat-uid-3"`                                                     |
      | name      | `String` | `"Nancy Grace"`                                                         |
      | avatar    | `String` | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"` |
    </Tab>

    <Tab title="Error Response">
      **Object Type:** [CometChatException](/sdk/ios/send-message#cometchatexception-object)

      | Parameter        | Type     | Value                                                     |
      | ---------------- | -------- | --------------------------------------------------------- |
      | errorCode        | `String` | `"ERROR_USER_NOT_LOGGED_IN"`                              |
      | errorDescription | `String` | `"Please log in to CometChat before calling this method"` |
    </Tab>
  </Tabs>
</Accordion>

***

## Messages for a group conversation

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

You can achieve this using the `setGUID()` method. This method takes the GUID of a group for which the conversations are to be fetched.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    var limit = 30;
    let messagesRequest = MessagesRequest.MessageRequestBuilder()
    .set(guid: "cometchat-guid-1")
    .set(limit: limit)
    .build();
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads">
  <Tabs>
    <Tab title="Request">
      **Method:** `MessagesRequest.fetchPrevious()`

      | Parameter | Type     | Value                |
      | --------- | -------- | -------------------- |
      | guid      | `String` | `"cometchat-guid-1"` |
      | limit     | `Int`    | `50`                 |
    </Tab>

    <Tab title="Success Response">
      **Return Type:** `[BaseMessage]`

      **Example [TextMessage](/sdk/ios/send-message#textmessage-object) in array:**

      | Parameter      | Type                     | Value                      |
      | -------------- | ------------------------ | -------------------------- |
      | id             | `Int`                    | `37791`                    |
      | muid           | `String`                 | `"1771917100.222222"`      |
      | conversationId | `String`                 | `"group_cometchat-guid-1"` |
      | senderUid      | `String`                 | `"cometchat-uid-3"`        |
      | receiverUid    | `String`                 | `"cometchat-guid-1"`       |
      | receiverType   | `CometChat.ReceiverType` | `1` (`.group`)             |
      | messageType    | `CometChat.MessageType`  | `0` (`.text`)              |
      | sentAt         | `Int`                    | `1771917100`               |
      | text           | `String`                 | `"Good morning everyone!"` |

      **sender** ([User](/sdk/ios/send-message#user-object)):

      | Parameter | Type     | Value                                                                   |
      | --------- | -------- | ----------------------------------------------------------------------- |
      | uid       | `String` | `"cometchat-uid-3"`                                                     |
      | name      | `String` | `"Nancy Grace"`                                                         |
      | avatar    | `String` | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"` |

      **receiver** ([Group](/sdk/ios/send-message#group-object)):

      | Parameter | Type                  | Value                                                                     |
      | --------- | --------------------- | ------------------------------------------------------------------------- |
      | guid      | `String`              | `"cometchat-guid-1"`                                                      |
      | name      | `String`              | `"Development Team"`                                                      |
      | icon      | `String`              | `"https://assets.cometchat.io/sampleapp/v2/groups/cometchat-guid-1.webp"` |
      | type      | `CometChat.GroupType` | `"public"`                                                                |
    </Tab>

    <Tab title="Error Response">
      **Object Type:** [CometChatException](/sdk/ios/send-message#cometchatexception-object)

      | Parameter        | Type     | Value                                                     |
      | ---------------- | -------- | --------------------------------------------------------- |
      | errorCode        | `String` | `"ERROR_USER_NOT_LOGGED_IN"`                              |
      | errorDescription | `String` | `"Please log in to CometChat before calling this method"` |
    </Tab>
  </Tabs>
</Accordion>

<Note>
  If none of the above two methods `setUID()` and `setGUID()` is used, all the messages for the logged-in user will be fetched. This means that messages from all the one-on-one and group conversations which the logged-in user is a part of will be returned.
</Note>

***

## Messages before/after a message

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

This can be achieved using the `setMessageId()` method. This method takes the message-id as input and provides messages only after/before the message-id based on if the fetchNext() or fetchPrevious() method is triggered.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    var limit = 30;
    let messagesRequest = MessagesRequest.MessageRequestBuilder()
    .set(messageID: 100)
    .set(limit: limit)
    .build();
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads">
  <Tabs>
    <Tab title="Request">
      **Method:** `MessagesRequest.fetchPrevious()`

      | Parameter | Type     | Value               |
      | --------- | -------- | ------------------- |
      | uid       | `String` | `"cometchat-uid-3"` |
      | messageID | `Int`    | `37797`             |
      | limit     | `Int`    | `30`                |
    </Tab>

    <Tab title="Success Response">
      **Return Type:** `[BaseMessage]` (messages before/after messageID 37797)

      **Example [TextMessage](/sdk/ios/send-message#textmessage-object) in array:**

      | Parameter      | Type                     | Value                                    |
      | -------------- | ------------------------ | ---------------------------------------- |
      | id             | `Int`                    | `37796`                                  |
      | muid           | `String`                 | `"1771917600.654321"`                    |
      | conversationId | `String`                 | `"cometchat-uid-2_user_cometchat-uid-3"` |
      | senderUid      | `String`                 | `"cometchat-uid-3"`                      |
      | receiverUid    | `String`                 | `"cometchat-uid-2"`                      |
      | receiverType   | `CometChat.ReceiverType` | `0` (`.user`)                            |
      | messageType    | `CometChat.MessageType`  | `0` (`.text`)                            |
      | sentAt         | `Int`                    | `1771917600`                             |
      | text           | `String`                 | `"Previous message"`                     |
    </Tab>

    <Tab title="Error Response">
      **Object Type:** [CometChatException](/sdk/ios/send-message#cometchatexception-object)

      | Parameter        | Type     | Value                                                     |
      | ---------------- | -------- | --------------------------------------------------------- |
      | errorCode        | `String` | `"ERROR_USER_NOT_LOGGED_IN"`                              |
      | errorDescription | `String` | `"Please log in to CometChat before calling this method"` |
    </Tab>
  </Tabs>
</Accordion>

***

## Messages before/after a given time

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

You can easily achieve this using the `setTimestamp()` method. This method takes the Unix timestamp as input.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    var limit = 30;
    let messagesRequest = MessagesRequest.MessageRequestBuilder()
    .set(timeStamp: 151268736300)
    .set(limit: limit)
    .build();
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads">
  <Tabs>
    <Tab title="Request">
      **Method:** `MessagesRequest.fetchPrevious()`

      | Parameter | Type     | Value               |
      | --------- | -------- | ------------------- |
      | uid       | `String` | `"cometchat-uid-3"` |
      | timeStamp | `Int`    | `1771848542`        |
      | limit     | `Int`    | `30`                |
    </Tab>

    <Tab title="Success Response">
      **Return Type:** `[BaseMessage]` (messages before/after timestamp)

      **Example [TextMessage](/sdk/ios/send-message#textmessage-object) in array:**

      | Parameter      | Type     | Value                                    |
      | -------------- | -------- | ---------------------------------------- |
      | id             | `Int`    | `37795`                                  |
      | muid           | `String` | `"1771848500.123456"`                    |
      | conversationId | `String` | `"cometchat-uid-2_user_cometchat-uid-3"` |
      | senderUid      | `String` | `"cometchat-uid-2"`                      |
      | receiverUid    | `String` | `"cometchat-uid-3"`                      |
      | sentAt         | `Int`    | `1771848500`                             |
      | text           | `String` | `"Message before timestamp"`             |
    </Tab>

    <Tab title="Error Response">
      **Object Type:** [CometChatException](/sdk/ios/send-message#cometchatexception-object)

      | Parameter        | Type     | Value                                                     |
      | ---------------- | -------- | --------------------------------------------------------- |
      | errorCode        | `String` | `"ERROR_USER_NOT_LOGGED_IN"`                              |
      | errorDescription | `String` | `"Please log in to CometChat before calling this method"` |
    </Tab>
  </Tabs>
</Accordion>

***

## Unread messages

*In other words, how do I fetch unread messages*

This can easily be achieved using setting the unread flag to true. For this, you need to use the `setUnread()` method.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    var limit = 30;
    let messagesRequest = MessagesRequest.MessageRequestBuilder()
    .set(unread: true)
    .set(limit: limit)
    .build();
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads">
  <Tabs>
    <Tab title="Request">
      **Method:** `MessagesRequest.fetchPrevious()`

      | Parameter | Type     | Value               |
      | --------- | -------- | ------------------- |
      | uid       | `String` | `"cometchat-uid-3"` |
      | unread    | `Bool`   | `true`              |
      | limit     | `Int`    | `30`                |
    </Tab>

    <Tab title="Success Response">
      **Return Type:** `[BaseMessage]` (unread messages only)

      **Example [TextMessage](/sdk/ios/send-message#textmessage-object) in array:**

      | Parameter      | Type     | Value                                    |
      | -------------- | -------- | ---------------------------------------- |
      | id             | `Int`    | `37799`                                  |
      | muid           | `String` | `"1771917874.691467"`                    |
      | conversationId | `String` | `"cometchat-uid-2_user_cometchat-uid-3"` |
      | senderUid      | `String` | `"cometchat-uid-3"`                      |
      | receiverUid    | `String` | `"cometchat-uid-2"`                      |
      | sentAt         | `Int`    | `1771917874`                             |
      | deliveredAt    | `Double` | `0.0`                                    |
      | readAt         | `Double` | `0.0`                                    |
      | text           | `String` | `"Unread message"`                       |
    </Tab>

    <Tab title="Error Response">
      **Object Type:** [CometChatException](/sdk/ios/send-message#cometchatexception-object)

      | Parameter        | Type     | Value                                                     |
      | ---------------- | -------- | --------------------------------------------------------- |
      | errorCode        | `String` | `"ERROR_USER_NOT_LOGGED_IN"`                              |
      | errorDescription | `String` | `"Please log in to CometChat before calling this method"` |
    </Tab>
  </Tabs>
</Accordion>

***

## Messages for multiple categories

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

For this, you will have to use the `setCategories()` method. This method accepts a list of categories.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    var limit = 30;
    let messagesRequest = MessagesRequest.MessageRequestBuilder()
    .set(limit: limit)
    .set(categories: ["message","call","action"])
    .build();
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads">
  <Tabs>
    <Tab title="Request">
      **Method:** `MessagesRequest.fetchPrevious()`

      | Parameter | Type     | Value               |
      | --------- | -------- | ------------------- |
      | uid       | `String` | `"cometchat-uid-3"` |
      | limit     | `Int`    | `30`                |

      **categories** (`[String]`):

      | Index | Type     | Value       |
      | ----- | -------- | ----------- |
      | 0     | `String` | `"message"` |
    </Tab>

    <Tab title="Success Response">
      **Return Type:** `[BaseMessage]` (filtered by categories)

      **Example [TextMessage](/sdk/ios/send-message#textmessage-object) in array:**

      | Parameter       | Type                        | Value                                    |
      | --------------- | --------------------------- | ---------------------------------------- |
      | id              | `Int`                       | `37798`                                  |
      | muid            | `String`                    | `"1771917734.123456"`                    |
      | conversationId  | `String`                    | `"cometchat-uid-2_user_cometchat-uid-3"` |
      | senderUid       | `String`                    | `"cometchat-uid-2"`                      |
      | receiverUid     | `String`                    | `"cometchat-uid-3"`                      |
      | messageCategory | `CometChat.MessageCategory` | `0` (`.message`)                         |
      | sentAt          | `Int`                       | `1771917734`                             |
      | text            | `String`                    | `"Hello"`                                |
    </Tab>

    <Tab title="Error Response">
      **Object Type:** [CometChatException](/sdk/ios/send-message#cometchatexception-object)

      | Parameter        | Type     | Value                                                     |
      | ---------------- | -------- | --------------------------------------------------------- |
      | errorCode        | `String` | `"ERROR_USER_NOT_LOGGED_IN"`                              |
      | errorDescription | `String` | `"Please log in to CometChat before calling this method"` |
    </Tab>
  </Tabs>
</Accordion>

***

## Messages for multiple types

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

This can be easily achieved using the `setTypes()` method. This method accepts a list of types.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    var limit = 30;
    let messagesRequest = MessagesRequest.MessageRequestBuilder()
    .set(limit: limit)
    .set(types: ["text","image"])
    .build();
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads">
  <Tabs>
    <Tab title="Request">
      **Method:** `MessagesRequest.fetchPrevious()`

      | Parameter | Type     | Value               |
      | --------- | -------- | ------------------- |
      | uid       | `String` | `"cometchat-uid-3"` |
      | limit     | `Int`    | `30`                |

      **types** (`[String]`):

      | Index | Type     | Value    |
      | ----- | -------- | -------- |
      | 0     | `String` | `"text"` |
    </Tab>

    <Tab title="Success Response">
      **Return Type:** `[BaseMessage]` (filtered by types)

      **Example [TextMessage](/sdk/ios/send-message#textmessage-object) in array:**

      | Parameter      | Type                    | Value                                    |
      | -------------- | ----------------------- | ---------------------------------------- |
      | id             | `Int`                   | `37798`                                  |
      | muid           | `String`                | `"1771917734.123456"`                    |
      | conversationId | `String`                | `"cometchat-uid-2_user_cometchat-uid-3"` |
      | senderUid      | `String`                | `"cometchat-uid-2"`                      |
      | receiverUid    | `String`                | `"cometchat-uid-3"`                      |
      | messageType    | `CometChat.MessageType` | `0` (`.text`)                            |
      | sentAt         | `Int`                   | `1771917734`                             |
      | text           | `String`                | `"Hello"`                                |
    </Tab>

    <Tab title="Error Response">
      **Object Type:** [CometChatException](/sdk/ios/send-message#cometchatexception-object)

      | Parameter        | Type     | Value                                                     |
      | ---------------- | -------- | --------------------------------------------------------- |
      | errorCode        | `String` | `"ERROR_USER_NOT_LOGGED_IN"`                              |
      | errorDescription | `String` | `"Please log in to CometChat before calling this method"` |
    </Tab>
  </Tabs>
</Accordion>

***

## Messages by tags

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

In order to do this, you can use the `setTags()` method. This method accepts a list of tags.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    var limit = 30
    let tags = ["pinned"]
    let messagesRequest = MessagesRequest.MessageRequestBuilder()
    .setLimit(50)
    .setTags(tags)
    .build();
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payloads">
  <Tabs>
    <Tab title="Request">
      **Method:** `MessagesRequest.fetchPrevious()`

      | Parameter | Type     | Value               |
      | --------- | -------- | ------------------- |
      | uid       | `String` | `"cometchat-uid-3"` |
      | limit     | `Int`    | `30`                |

      **tags** (`[String]`):

      | Index | Type     | Value         |
      | ----- | -------- | ------------- |
      | 0     | `String` | `"important"` |
    </Tab>

    <Tab title="Success Response">
      **Return Type:** `[BaseMessage]` (with specified tags)

      **Example [TextMessage](/sdk/ios/send-message#textmessage-object) in array:**

      | Parameter      | Type     | Value                                    |
      | -------------- | -------- | ---------------------------------------- |
      | id             | `Int`    | `37798`                                  |
      | muid           | `String` | `"1771917734.123456"`                    |
      | conversationId | `String` | `"cometchat-uid-2_user_cometchat-uid-3"` |
      | senderUid      | `String` | `"cometchat-uid-2"`                      |
      | receiverUid    | `String` | `"cometchat-uid-3"`                      |
      | sentAt         | `Int`    | `1771917734`                             |
      | text           | `String` | `"Important message"`                    |

      **tags** (`[String]`):

      | Index | Type     | Value         |
      | ----- | -------- | ------------- |
      | 0     | `String` | `"important"` |
    </Tab>

    <Tab title="Error Response">
      **Object Type:** [CometChatException](/sdk/ios/send-message#cometchatexception-object)

      | Parameter        | Type     | Value                                                     |
      | ---------------- | -------- | --------------------------------------------------------- |
      | errorCode        | `String` | `"ERROR_USER_NOT_LOGGED_IN"`                              |
      | errorDescription | `String` | `"Please log in to CometChat before calling this method"` |
    </Tab>
  </Tabs>
</Accordion>

***

## Common Error Codes

| Error Code                 | Description                | Resolution                          |
| -------------------------- | -------------------------- | ----------------------------------- |
| `ERROR_USER_NOT_LOGGED_IN` | User is not logged in      | Call `CometChat.login()` first      |
| `ERR_SDK_NOT_INITIALIZED`  | SDK not initialized        | Call `CometChat.init()` first       |
| `ERR_NETWORK_ERROR`        | Network connectivity issue | Check internet connection and retry |
| `ERR_INVALID_UID`          | Invalid user UID           | Verify the UID exists               |
| `ERR_INVALID_GUID`         | Invalid group GUID         | Verify the GUID exists              |