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

# Message Filtering

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

<Accordion title="AI Integration Quick Reference">
  ```swift theme={null}
  // Filter by category and type
  let mediaRequest = MessagesRequest.MessageRequestBuilder()
    .set(uid: "cometchat-uid-1")
    .set(categories: ["message"])
    .set(types: ["image", "video", "audio", "file"])
    .set(limit: 50)
    .build()

  // Unread messages only
  let unreadRequest = MessagesRequest.MessageRequestBuilder()
    .set(uid: "cometchat-uid-1")
    .set(unread: true)
    .set(limit: 50)
    .build()

  // Fetch with pagination
  messagesRequest.fetchPrevious(onSuccess: { messages in }, onError: { error in })
  messagesRequest.fetchNext(onSuccess: { messages in }, onError: { error in })
  ```

  **Key methods:** `set(uid:)`, `set(guid:)`, `set(limit:)`, `set(categories:)`, `set(types:)`, `setTags(_:)`, `set(unread:)`, `setParentMessageId(parentMessageId:)`, `set(messageID:)`, `set(timeStamp:)`, `hideReplies(hide:)`, `hideDeletedMessages(hide:)`
</Accordion>

The `MessagesRequest` class fetches messages based on various parameters. It uses the Builder design pattern via `MessagesRequestBuilder`.

| 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. Call `fetchPrevious()`/`fetchNext()` repeatedly on the same object to get subsequent pages.

Both methods return an array of [`BaseMessage`](/sdk/reference/messages#basemessage) objects. Each message may be a [`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). Use type checking to determine the specific type.

## Number of messages fetched

Set the number of messages to fetch per request using `setLimit()`. Maximum is 100.

```swift theme={null}
var limit = 50
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .set(limit: limit)
  .build()
```

## Messages for a user conversation

Use `set(uid:)` to fetch messages between the logged-in user and a specific user.

```swift theme={null}
var limit = 30
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .set(uid: "cometchat-uid-1")
  .set(limit: limit)
  .build()
```

## Messages for a group conversation

Use `set(guid:)` to fetch messages from a group.

```swift theme={null}
var limit = 30
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .set(guid: "cometchat-guid-1")
  .set(limit: limit)
  .build()
```

<Note>
  If neither `set(uid:)` nor `set(guid:)` is used, all messages for the logged-in user will be fetched across all conversations.
</Note>

## Messages before/after a message

Use `set(messageID:)` to fetch messages before or after a specific message ID. Use `fetchNext()` to get messages after, or `fetchPrevious()` to get messages before.

```swift theme={null}
var limit = 30
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .set(messageID: 100)
  .set(limit: limit)
  .build()
```

## Messages before/after a given time

Use `set(timeStamp:)` with a Unix timestamp to fetch messages before or after a specific time.

```swift theme={null}
var limit = 30
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .set(timeStamp: 151268736300)
  .set(limit: limit)
  .build()
```

## Unread messages

Use `set(unread:)` to fetch only unread messages.

```swift theme={null}
var limit = 30
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .set(unread: true)
  .set(limit: limit)
  .build()
```

## Messages for multiple categories

Use `set(categories:)` with an array of category names. See [Message structure and hierarchy](/sdk/ios/message-structure-and-hierarchy) for available categories.

```swift theme={null}
var limit = 30
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .set(limit: limit)
  .set(categories: ["message", "call", "action"])
  .build()
```

## Messages for multiple types

Use `set(types:)` with an array of type names.

```swift theme={null}
var limit = 30
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .set(limit: limit)
  .set(types: ["text", "image"])
  .build()
```

## Messages by tags

Use `setTags()` with an array of tag names to fetch only messages with those tags.

```swift theme={null}
var limit = 30
let tags = ["pinned"]
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .setLimit(50)
  .setTags(tags)
  .build()
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Receive Messages" icon="inbox" href="/sdk/ios/receive-message">
    Listen for incoming messages in real-time
  </Card>

  <Card title="Threaded Messages" icon="comments" href="/sdk/ios/threaded-messages">
    Organize conversations with message threads
  </Card>

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