Message Filtering

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

AI Integration Quick Reference

// 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:)

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 objects. Each message may be a TextMessage, MediaMessage, CustomMessage, Action, or 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.

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.

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.

var limit = 30
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .set(guid: "cometchat-guid-1")
  .set(limit: limit)
  .build()

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

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.

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.

var limit = 30
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .set(timeStamp: 151268736300)
  .set(limit: limit)
  .build()

Unread messages

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

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 for available categories.

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.

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.

var limit = 30
let tags = ["pinned"]
let messagesRequest = MessagesRequest.MessageRequestBuilder()
  .setLimit(50)
  .setTags(tags)
  .build()

---

Next Steps

Receive Messages

Listen for incoming messages in real-time

Threaded Messages

Organize conversations with message threads

Message Structure

Understand message categories and types