Retrieve Conversations - CometChat Docs

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. The ConversationsRequestBuilder class allows you to set the below parameters:

Set Limit

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

Dart

ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
  ..limit = 50
).build();

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:

user - Only fetches user conversation.
group - Only fetches group conversations.

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

Dart

ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
  ..limit = 50
  ..conversationType = CometChatConversationType.user
).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.

Dart

ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
  ..limit = 50
  ..withUserAndGroupTags  = true
).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

Dart

ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
  ..limit = 50
  ..withTags = true
).build();

Set Tags

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

Dart

List<String> tags = [];
tags.add("archived");
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
  ..limit = 50
  ..tags = tags
).build();

Include Blocked Users

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

Dart

ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
  ..limit = 50
  ..includeBlockedUsers = true
).build();

With Blocked Info

This method can be used to fetch the blocked information of the blocked user in the ConversationWith object.

Dart

ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
  ..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)

Dart

  ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
    ..limit = 50
    ..searchKeyword = "Hiking"
  ).build();

Unread Conversations

This method helps you fetch unread conversations.

Dart

  ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
    ..limit = 50
    ..unread = true
  ).build();

Filter by User Tags

This method helps you filter conversations based on specific user tags.

Dart

List<String> userTags = ["premium", "verified"];
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
  ..limit = 50
  ..userTags = userTags
).build();

Filter by Group Tags

This method helps you filter conversations based on specific group tags.

Dart

List<String> groupTags = ["support", "sales"];
ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
  ..limit = 50
  ..groupTags = groupTags
).build();

Hide Agentic Conversations

This method helps you hide AI-driven (agentic) conversations from the list. Agentic conversations are those involving AI agents.

Dart

ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
  ..limit = 50
  ..hideAgentic = true
).build();

Only Agentic Conversations

This method helps you fetch only AI-driven (agentic) conversations. This is useful when you want to display a separate list of AI agent conversations.

Dart

ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
  ..limit = 50
  ..onlyAgentic = true
).build();

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. A Maximum of only 50 Conversations can be fetched at once.

Dart

ConversationsRequest conversationRequest = (ConversationsRequestBuilder()
    ..limit = 50
  ).build();

conversationRequest.fetchNext(
      onSuccess: (List<Conversation> conversations){


      }, onError: (CometChatException e){

      }

The Conversationobject consists of the below fields:

Field	Information
`conversationId`	ID of the conversation
`conversationType`	Type of conversation (user/group)
`lastMessage`	Last message the conversation
`conversationWith`	`User` or `Group` object containing the details of the user or group
`unreadMessageCount`	Unread message count for the conversation
`unreadMentionsCount`	the count of unread mentions in the conversation.
`lastReadMessageId`	the ID of the last read message in the conversation (int type).

Tag Conversation

In other words, as a logged-in user, how do I tag a conversation? In order to tag a specific conversation, you can use the tagConversation() method. The tagConversation() method accepts three parameters.

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

Dart

String conversationWith = "cometchat-uid-1"; //id of the user/group
String conversationType = "user";
List<String> tags = [];
tags.add("archived");

CometChat.tagConversation(conversationWith, conversationType, tags,
	onSuccess: (Conversation conversation) {
		debugPrint("Conversation tagged Successfully : $conversation");
	}, onError: (CometChatException e) {
		debugPrint("Conversation tagging failed  : ${e.message}");
	}
);

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.

Retrieve Single Conversation

In other words, as a logged-in user, how do I retrieve a specific conversation? In order to fetch a specific conversation, you can use the getConversation method. The getConversation method accepts two parameters.

conversationWith: UID/GUID of the user/group whose conversation you want to fetch.
conversationType: The conversationType variable can hold one of the below two values:

user - Only fetches user conversation.
group - Only fetches group conversations.

Dart

String conversationWith = "cometchat-uid-1"; //id of the user/group
String conversationType = "user";
CometChat.getConversation(conversationWith, conversationType,
	onSuccess: (Conversation conversation) {
		debugPrint("Fetch Conversation Successfully : $conversation");
	}, onError: (CometChatException e) {
		debugPrint("Fetch Conversation  failed  : ${e.message}");
	}
);

Convert Messages to Conversations

As per our Receive Messages guide, for real-time messages, 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 for this purpose.

Dart

Conversation conversation = CometChat.getConversationFromMessage(message);

While converting Message object to 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.

​Retrieve List of Conversations

​Set Limit

​Set Conversation Type

​With User and Group Tags

​With Tags

​Set Tags

​Include Blocked Users

​With Blocked Info

​Search Conversations

​Unread Conversations

​Filter by User Tags

​Filter by Group Tags

​Hide Agentic Conversations

​Only Agentic Conversations

​Tag Conversation

​Retrieve Single Conversation

​Convert Messages to Conversations

Retrieve List of Conversations

Set Limit

Set Conversation Type

With User and Group Tags

With Tags

Set Tags

Include Blocked Users

With Blocked Info

Search Conversations

Unread Conversations

Filter by User Tags

Filter by Group Tags

Hide Agentic Conversations

Only Agentic Conversations

Tag Conversation

Retrieve Single Conversation

Convert Messages to Conversations