Additional Message Filtering

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 · Message Structure · Messaging Overview

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:

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.

Swift

var limit = 50;
let messagesRequest = MessagesRequest.MessageRequestBuilder()
.set(limit: limit)
.build();

Sample Payloads

Request
Success Response
Error Response

Method: MessagesRequest.fetchPrevious()

Parameter	Type	Value
limit	`Int`	`30`

Return Type: [BaseMessage] (Array of up to 30 messages)Example TextMessage 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):

Parameter	Type	Value
uid	`String`	`"cometchat-uid-2"`
name	`String`	`"George Alan"`

Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"ERROR_USER_NOT_LOGGED_IN"`
errorDescription	`String`	`"Please log in to CometChat before calling this method"`

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.

Swift

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

Sample Payloads

Request
Success Response
Error Response

Method: MessagesRequest.fetchPrevious()

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

Return Type: [BaseMessage]Example TextMessage 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):

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

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

Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"ERROR_USER_NOT_LOGGED_IN"`
errorDescription	`String`	`"Please log in to CometChat before calling this method"`

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.

Swift

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

Sample Payloads

Request
Success Response
Error Response

Method: MessagesRequest.fetchPrevious()

Parameter	Type	Value
guid	`String`	`"cometchat-guid-1"`
limit	`Int`	`50`

Return Type: [BaseMessage]Example TextMessage 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):

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

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

Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"ERROR_USER_NOT_LOGGED_IN"`
errorDescription	`String`	`"Please log in to CometChat before calling this method"`

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.

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.

Swift

var limit = 30;
let messagesRequest = MessagesRequest.MessageRequestBuilder()
.set(messageID: 100)
.set(limit: limit)
.build();

Sample Payloads

Request
Success Response
Error Response

Method: MessagesRequest.fetchPrevious()

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

Return Type: [BaseMessage] (messages before/after messageID 37797)Example TextMessage 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"`

Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"ERROR_USER_NOT_LOGGED_IN"`
errorDescription	`String`	`"Please log in to CometChat before calling this method"`

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.

Swift

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

Sample Payloads

Request
Success Response
Error Response

Method: MessagesRequest.fetchPrevious()

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

Return Type: [BaseMessage] (messages before/after timestamp)Example TextMessage 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"`

Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"ERROR_USER_NOT_LOGGED_IN"`
errorDescription	`String`	`"Please log in to CometChat before calling this method"`

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.

Swift

var limit = 30;
let messagesRequest = MessagesRequest.MessageRequestBuilder()
.set(unread: true)
.set(limit: limit)
.build();

Sample Payloads

Request
Success Response
Error Response

Method: MessagesRequest.fetchPrevious()

Parameter	Type	Value
uid	`String`	`"cometchat-uid-3"`
unread	`Bool`	`true`
limit	`Int`	`30`

Return Type: [BaseMessage] (unread messages only)Example TextMessage 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"`

Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"ERROR_USER_NOT_LOGGED_IN"`
errorDescription	`String`	`"Please log in to CometChat before calling this method"`

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.

Swift

var limit = 30;
let messagesRequest = MessagesRequest.MessageRequestBuilder()
.set(limit: limit)
.set(categories: ["message","call","action"])
.build();

Sample Payloads

Request
Success Response
Error Response

Method: MessagesRequest.fetchPrevious()

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

categories ([String]):

Index	Type	Value
0	`String`	`"message"`

Return Type: [BaseMessage] (filtered by categories)Example TextMessage 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"`

Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"ERROR_USER_NOT_LOGGED_IN"`
errorDescription	`String`	`"Please log in to CometChat before calling this method"`

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.

Swift

var limit = 30;
let messagesRequest = MessagesRequest.MessageRequestBuilder()
.set(limit: limit)
.set(types: ["text","image"])
.build();

Sample Payloads

Request
Success Response
Error Response

Method: MessagesRequest.fetchPrevious()

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

types ([String]):

Index	Type	Value
0	`String`	`"text"`

Return Type: [BaseMessage] (filtered by types)Example TextMessage 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"`

Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"ERROR_USER_NOT_LOGGED_IN"`
errorDescription	`String`	`"Please log in to CometChat before calling this method"`

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.

Swift

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

Sample Payloads

Request
Success Response
Error Response

Method: MessagesRequest.fetchPrevious()

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

tags ([String]):

Index	Type	Value
0	`String`	`"important"`

Return Type: [BaseMessage] (with specified tags)Example TextMessage 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"`

Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"ERROR_USER_NOT_LOGGED_IN"`
errorDescription	`String`	`"Please log in to CometChat before calling this method"`

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

​Object Structures

​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

​Messages for multiple categories

​Messages for multiple types

​Messages by tags

​Common Error Codes

Object Structures

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

Messages for multiple categories

Messages for multiple types

Messages by tags

Common Error Codes