Retrieve Conversations

Guide to fetching conversation lists using the CometChat iOS SDK ConversationsRequest builder with filtering and pagination.

Quick Reference for AI Agents & Developers

• Build request: ConversationRequest.ConversationRequestBuilder(limit:).build()
• Fetch conversations: conversationsRequest.fetchNext(onSuccess:onError:)
• Filters: .setConversationType(conversationType:), .setTags(_:), .withUserAndGroupTags()
• Related: Delete Conversation · Messaging Overview

CometChat Allows you to fetch the list of conversations the logged-in user is a part of. This list of conversations consists of both user and group conversations.

---

Object Structures

Conversation Object

The Conversation object represents a conversation in CometChat.

Parameter	Type	Description
conversationId	String	Unique conversation identifier
conversationType	CometChat.ConversationType	.user (0) or .group (1)
lastMessage	BaseMessage	Last message in the conversation
conversationWith	User or Group	User or Group object
unreadMessageCount	Int	Number of unread messages
unreadMentionsCount	Int	Number of unread mentions
lastReadMessageId	Int	ID of the last read message
updatedAt	Double	Unix timestamp of last update
tags	[String]?	Array of conversation tags

For other object structures, see Send Message - Object Structures.

---

Retrieve List of Conversations

In other words, as a logged-in user, how do I retrieve the latest conversations that I’ve been a part of?

To fetch the list of conversations, you can use the ConversationsRequest class. To use this class i.e. to create an object of the ConversationsRequest class, you need to use the ConversationsRequestBuilder class. The ConversationsRequestBuilder class allows you to set the parameters based on which the conversations are to be fetched.

Set Limit

This method sets the limit i.e. the number of conversations that should be fetched in a single iteration.

Swift

var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 30)
  .build()

A Maximum of only 50 Conversations can be fetched at once. If you want to fetch more conversations, you can use the fetchNext() on the same conversationsRequest object.

Set Conversation Type

This method can be used to fetch user or group conversations specifically. The conversationType variable can hold one of the below two values:

• CometChat.ConversationType.user - Only fetches user conversations.
• CometChat.ConversationType.group - Only fetches group conversations.

If none is set, the list of conversations will include both user and group conversations.

Swift (User)

var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
  .setConversationType(conversationType: .user)
  .build()

Swift (Group)

var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
  .setConversationType(conversationType: .group)
  .build()

With User and Group Tags

This method can be used to fetch the user/group tags in the Conversation Object. By default the value is false.

Swift

var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
  .withUserAndGroupTags(true)
  .build()

Set User Tags

This method fetches user conversations which have the specified tags.

Swift

let limit = 30
let userTags = ["tag1"]
let conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: limit)
  .setUserTags(userTags)
  .build()

Set Group Tags

This method fetches group conversations which have the specified tags.

Swift

let limit = 30
let groupTags = ["tag1"]
let conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: limit)
  .setGroupTags(groupTags)
  .build()

With Tags

This method makes sure that the tags associated with the conversations are returned along with the other details of the conversations. The default value for this parameter is false.

Swift

var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
  .withTags(true)
  .build()

Set Tags

This method helps you fetch the conversations based on the specified tags.

Swift

let tags = ["pinned", "archived"]
var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
  .setTags(tags)
  .build()

Include Blocked Users

This method helps you fetch the conversations of users whom the logged-in user has blocked.

Swift

var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
  .includeBlockedUsers(true)
  .build()

With Blocked Info

This method helps you fetch the blocked information in the Conversation object.

Swift

var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
  .withBlockedInfo(true)
  .build()

Search Conversations

This method helps you search a conversation based on User or Group name.

This feature is only available with Conversation & Advanced Search. The Conversation & Advanced Search is only available in Advanced & Custom plans. If you’re already on one of these plans, please enable the Conversation & Advanced Search from CometChat Dashboard (Open your app, navigate to Chats -> Settings -> General Configuration)

Swift

var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
  .setSearchKeyword("Hiking")
  .build()

Unread Conversations

This method helps you fetch unread conversations.

This feature is only available with Conversation & Advanced Search. The Conversation & Advanced Search is only available in Advanced & Custom plans. If you’re already on one of these plans, please enable the Conversation & Advanced Search from CometChat Dashboard (Open your app, navigate to Chats -> Settings -> General Configuration)

Swift

var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
  .setUnread(true)
  .build()

---

Fetch Conversations

Finally, once all the parameters are set to the builder class, you need to call the build() method to get the object of the ConversationsRequest class.

Once you have the object of the ConversationsRequest class, you need to call the fetchNext() method. Calling this method will return a list of Conversation objects containing X number of conversations depending on the limit set.

Swift (User)

let convRequest = ConversationRequest.ConversationRequestBuilder(limit: 20)
  .setConversationType(conversationType: .user)
  .build()

convRequest.fetchNext(onSuccess: { (conversationList) in
  print("success of convRequest \(conversationList)")            
}) { (exception) in
  print("here exception \(String(describing: exception?.errorDescription))")
}

Swift (Group)

let convRequest = ConversationRequest.ConversationRequestBuilder(limit: 20)
  .setConversationType(conversationType: .group)
  .build()

convRequest.fetchNext(onSuccess: { (conversationList) in
  print("success of convRequest \(conversationList)")            
}) { (exception) in
  print("here exception \(String(describing: exception?.errorDescription))")
}

The Conversation object consists of the following fields:

Field	Information
conversationId	ID of the conversation
conversationType	Type of conversation (user/group)
lastMessage	Last message in the conversation
conversationWith	User or Group object containing the details of the user or group
unreadMessageCount	Unread message count for the conversation

Sample Payloads

Request

Method: conversationsRequest.fetchNext(onSuccess:onError:)

Object Type: ConversationRequest

Parameter	Type	Value
limit	Int	20
conversationType	CometChat.ConversationType?	0 (.user)

Success Response

Object Type: [Conversation] (Array of Conversation)

Conversation[0]:

Parameter	Type	Value
conversationId	String	"cometchat-uid-2_user_cometchat-uid-3"
conversationType	CometChat.ConversationType	0 (.user)
unreadMessageCount	Int	5
unreadMentionsCount	Int	0
lastReadMessageId	Int	37790
updatedAt	Double	1771917734.0
tags	[String]?	nil

lastMessage (TextMessage):

Parameter	Type	Value
id	Int	37798
muid	String	""
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)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1771917734
text	String	"Hello"

conversationWith (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"
link	String?	nil
role	String	"moderator"
status	CometChat.UserStatus	0 (.online)
statusMessage	String?	nil
lastActiveAt	Double	1771586880.0
hasBlockedMe	Bool	false
blockedByMe	Bool	false
metadata	[String: Any]	[:] (empty dictionary)
deactivatedAt	Double	0.0

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_NOT_LOGGED_IN"
errorDescription	String	"User is not logged in. Please login first."
details	String?	nil

More Sample Payloads

Group Conversation

Object Type: Conversation

Parameter	Type	Value
conversationId	String	"group_cometchat-guid-101"
conversationType	CometChat.ConversationType	1 (.group)
unreadMessageCount	Int	12
unreadMentionsCount	Int	2
lastReadMessageId	Int	37650
updatedAt	Double	1771915000.0
tags	[String]?	nil

lastMessage (TextMessage):

Parameter	Type	Value
id	Int	37662
muid	String	""
conversationId	String	"group_cometchat-guid-101"
senderUid	String	"cometchat-uid-4"
receiverUid	String	"cometchat-guid-101"
receiverType	CometChat.ReceiverType	1 (.group)
messageType	CometChat.MessageType	0 (.text)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1771915000
text	String	"Team meeting at 3 PM"

conversationWith (Group):

Parameter	Type	Value
guid	String	"cometchat-guid-101"
name	String	"Development Team"
icon	String	"https://assets.cometchat.io/sampleapp/v2/groups/cometchat-guid-101.webp"
description	String	"Team for development discussions"
type	CometChat.GroupType	"public"
owner	String	"cometchat-uid-1"
membersCount	Int	15
createdAt	Double	1700000000.0
updatedAt	Double	1771915000.0
hasJoined	Bool	true
joinedAt	Double	1705000000.0
scope	CometChat.GroupMemberScope	"participant"
metadata	[String: Any]?	nil
tags	[String]?	nil

With Tags

Object Type: Conversation

Parameter	Type	Value
conversationId	String	"cometchat-uid-2_user_cometchat-uid-5"
conversationType	CometChat.ConversationType	0 (.user)
unreadMessageCount	Int	0
unreadMentionsCount	Int	0
lastReadMessageId	Int	37500
updatedAt	Double	1771900000.0

tags ([String]):

Index	Type	Value
0	String	"pinned"
1	String	"important"

conversationWith (User):

Parameter	Type	Value
uid	String	"cometchat-uid-5"
name	String	"Andrew Joseph"
avatar	String	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-5.webp"
status	CometChat.UserStatus	1 (.offline)
lastActiveAt	Double	1771800000.0

With Media Last Message

Object Type: Conversation

Parameter	Type	Value
conversationId	String	"cometchat-uid-2_user_cometchat-uid-6"
conversationType	CometChat.ConversationType	0 (.user)
unreadMessageCount	Int	1
unreadMentionsCount	Int	0
lastReadMessageId	Int	37700
updatedAt	Double	1771910000.0
tags	[String]?	nil

lastMessage (MediaMessage):

Parameter	Type	Value
id	Int	37705
muid	String	""
conversationId	String	"cometchat-uid-2_user_cometchat-uid-6"
senderUid	String	"cometchat-uid-6"
receiverUid	String	"cometchat-uid-2"
receiverType	CometChat.ReceiverType	0 (.user)
messageType	CometChat.MessageType	1 (.image)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1771910000
caption	String?	"Check this out!"

lastMessage.attachment (Attachment):

Parameter	Type	Value
fileName	String	"photo.jpg"
fileExtension	String	"jpg"
fileSize	Int	245678
fileMimeType	String	"image/jpeg"
fileUrl	String	"https://data-us.cometchat.io/assets/images/photo.jpg"

---

Tag Conversation

In other words, as a logged-in user, how do I tag a conversation?

To tag a specific conversation, you can use the tagConversation() method. The tagConversation() method accepts three parameters:

1. conversationWith: UID/GUID of the user/group whose conversation you want to tag.
2. conversationType: The conversationType variable can hold one of the below two values:
   • user - Only fetches user conversation.
   • group - Only fetches group conversations.
3. tags: The tags variable will be a list of tags you want to add to a conversation.

Swift

let id = "cometchat-uid-1" // id of the user/group
let tags = ["pinned"]

CometChat.tagConversation(conversationWith: id, conversationType: .user, tags: tags, onSuccess: { conversation in
  print("conversation", conversation)
}, onError: { error in
  print("error", error)
})

The tags for conversations are one-way. This means that if user A tags a conversation with user B, that tag will be applied to that conversation only for user A.

Sample Payloads

Request

Method: CometChat.tagConversation(conversationWith:conversationType:tags:onSuccess:onError:)

Parameter	Type	Value
conversationWith	String	"cometchat-uid-3"
conversationType	CometChat.ConversationType	0 (.user)

tags ([String]):

Index	Type	Value
0	String	"pinned"

Success Response

Object Type: Conversation

Parameter	Type	Value
conversationId	String	"cometchat-uid-2_user_cometchat-uid-3"
conversationType	CometChat.ConversationType	0 (.user)
unreadMessageCount	Int	5
unreadMentionsCount	Int	0
lastReadMessageId	Int	37790
updatedAt	Double	1771917734.0

tags ([String]):

Index	Type	Value
0	String	"pinned"

conversationWith (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"
status	CometChat.UserStatus	0 (.online)

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_NOT_LOGGED_IN"
errorDescription	String	"User is not logged in. Please login first."
details	String?	nil

---

Retrieve Single Conversation

In other words, as a logged-in user, how do I retrieve a specific conversation?

To fetch a specific conversation, you can use the getConversation method. The getConversation method accepts two parameters:

1. conversationWith: UID/GUID of the user/group whose conversation you want to fetch.
2. conversationType: The conversationType variable can hold one of the below two values:
   • user - Only fetches user conversation.
   • group - Only fetches group conversations.

Swift (User)

CometChat.getConversation(conversationWith: "cometchat-uid-3", conversationType: .user, onSuccess: { conversation in
  print("success \(String(describing: conversation?.stringValue()))")
}) { error in
  print("error \(String(describing: error?.errorDescription))")
}

Swift (Group)

CometChat.getConversation(conversationWith: "cometchat-guid-101", conversationType: .group, onSuccess: { conversation in
  print("success \(String(describing: conversation?.stringValue()))")
}) { error in
  print("error \(String(describing: error?.errorDescription))")
}

Sample Payloads

Request

Method: CometChat.getConversation(conversationWith:conversationType:onSuccess:onError:)

Parameter	Type	Value
conversationWith	String	"cometchat-uid-3"
conversationType	CometChat.ConversationType	0 (.user)

Success Response

Object Type: Conversation

Parameter	Type	Value
conversationId	String	"cometchat-uid-2_user_cometchat-uid-3"
conversationType	CometChat.ConversationType	0 (.user)
unreadMessageCount	Int	5
unreadMentionsCount	Int	0
lastReadMessageId	Int	37790
updatedAt	Double	1771917734.0
tags	[String]?	nil

lastMessage (TextMessage):

Parameter	Type	Value
id	Int	37798
muid	String	""
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)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1771917734
text	String	"Hello"

conversationWith (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"
link	String?	nil
role	String	"moderator"
status	CometChat.UserStatus	0 (.online)
statusMessage	String?	nil
lastActiveAt	Double	1771586880.0
hasBlockedMe	Bool	false
blockedByMe	Bool	false
metadata	[String: Any]	[:] (empty dictionary)
deactivatedAt	Double	0.0

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_CONVERSATION_NOT_FOUND"
errorDescription	String	"Conversation not found."
details	String?	nil

More Sample Payloads - Single Conversation

Group Conversation

Object Type: Conversation

Parameter	Type	Value
conversationId	String	"group_cometchat-guid-101"
conversationType	CometChat.ConversationType	1 (.group)
unreadMessageCount	Int	12
unreadMentionsCount	Int	2
lastReadMessageId	Int	37650
updatedAt	Double	1771915000.0
tags	[String]?	nil

lastMessage (TextMessage):

Parameter	Type	Value
id	Int	37662
muid	String	""
conversationId	String	"group_cometchat-guid-101"
senderUid	String	"cometchat-uid-4"
receiverUid	String	"cometchat-guid-101"
receiverType	CometChat.ReceiverType	1 (.group)
messageType	CometChat.MessageType	0 (.text)
sentAt	Int	1771915000
text	String	"Team meeting at 3 PM"

conversationWith (Group):

Parameter	Type	Value
guid	String	"cometchat-guid-101"
name	String	"Development Team"
icon	String	"https://assets.cometchat.io/sampleapp/v2/groups/cometchat-guid-101.webp"
description	String	"Team for development discussions"
type	CometChat.GroupType	"public"
owner	String	"cometchat-uid-1"
membersCount	Int	15
hasJoined	Bool	true
scope	CometChat.GroupMemberScope	"participant"

With Custom Message

Object Type: Conversation

Parameter	Type	Value
conversationId	String	"cometchat-uid-2_user_cometchat-uid-7"
conversationType	CometChat.ConversationType	0 (.user)
unreadMessageCount	Int	1
unreadMentionsCount	Int	0
lastReadMessageId	Int	37800
updatedAt	Double	1771920000.0
tags	[String]?	nil

lastMessage (CustomMessage):

Parameter	Type	Value
id	Int	37805
muid	String	""
conversationId	String	"cometchat-uid-2_user_cometchat-uid-7"
senderUid	String	"cometchat-uid-7"
receiverUid	String	"cometchat-uid-2"
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	3 (.custom)
customType	String	"location"
sentAt	Int	1771920000
conversationText	String	"📍 Shared a location"

lastMessage.customData ([String: Any]):

Key	Type	Value
latitude	String	"37.7749"
longitude	String	"-122.4194"
address	String	"San Francisco, CA"

---

Get Conversation From Message

For real-time events, you will always receive Message objects and not Conversation objects. Thus, you will need a mechanism to convert the Message object to a Conversation object. You can use the getConversationFromMessage() method of the CometChat class.

Swift

let myConversation = CometChat.getConversationFromMessage(message)

While converting a Message object to a Conversation object, the unreadMessageCount & tags will not be available in the Conversation object. The unread message count needs to be managed in your client-side code.

Sample Payloads

Request

Method: CometChat.getConversationFromMessage(_:)

Input Object Type: TextMessage

Parameter	Type	Value
id	Int	37798
muid	String	""
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)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1771917734
text	String	"Hello"

Success Response

Object Type: Conversation

Parameter	Type	Value
conversationId	String	"cometchat-uid-2_user_cometchat-uid-3"
conversationType	CometChat.ConversationType	0 (.user)
unreadMessageCount	Int	0
unreadMentionsCount	Int	0
lastReadMessageId	Int	0
updatedAt	Double	1771917734.0
tags	[String]?	nil

lastMessage (TextMessage):

Parameter	Type	Value
id	Int	37798
muid	String	""
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	1771917734
text	String	"Hello"

conversationWith (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"
status	CometChat.UserStatus	0 (.online)

---

Common Error Codes

Error Code	Description	Resolution
ERR_NOT_LOGGED_IN	User is not logged in	Call CometChat.login() first
ERR_CONVERSATION_NOT_FOUND	Conversation does not exist	Verify the conversationWith and conversationType parameters
ERR_INVALID_CONVERSATION_TYPE	Invalid conversation type provided	Use .user or .group
ERR_SDK_NOT_INITIALIZED	SDK not initialized	Call CometChat.init() first
ERR_NETWORK_ERROR	Network connectivity issue	Check internet connection and retry
ERR_FEATURE_NOT_ENABLED	Feature not enabled for your plan	Enable the feature from CometChat Dashboard or upgrade plan