> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve Conversations
> Fetch, filter, tag, and search CometChat conversations with the iOS SDK for one-on-one and group chats.
```swift theme={null}
// Fetch conversations list
let request = ConversationRequest.ConversationRequestBuilder(limit: 30).build()
request.fetchNext(onSuccess: { conversations in }, onError: { error in })
// Get a specific conversation
CometChat.getConversation(conversationWith: "UID", conversationType: .user, onSuccess: { conv in }, onError: { error in })
// Tag a conversation
CometChat.tagConversation(conversationWith: "UID", conversationType: .user, tags: ["archived"], onSuccess: { conv in }, onError: { error in })
// Convert message to conversation
let conv = CometChat.getConversationFromMessage(message)
```
Conversations provide the last message for every one-on-one and group conversation the logged-in user is part of. Each [`Conversation`](/sdk/reference/entities#conversation) object includes the other participant (user or group), the last message, unread counts, and optional tags. Use this to build a Recent Chats list.
## Retrieve List of Conversations
Use `ConversationsRequest` with `ConversationsRequestBuilder` to fetch conversations with various filters.
### Set Limit
Set the number of conversations to fetch per request. Maximum is 50.
```swift theme={null}
var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 30).build()
```
### Set Conversation Type
Filter by conversation type: `.user` for one-on-one or `.group` for group conversations. If not set, both types are returned.
```swift theme={null}
var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
.setConversationType(conversationType: .user)
.build()
```
```swift theme={null}
var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
.setConversationType(conversationType: .group)
.build()
```
### With User and Group Tags
Use `withUserAndGroupTags(true)` to include user/group tags in the response. Default is `false`.
```swift theme={null}
var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
.withUserAndGroupTags(true)
.build()
```
### Set User Tags
Fetch user conversations where the user has specific tags.
```swift theme={null}
let limit = 30
let userTags = ["tag1"]
let conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: limit)
.setUserTags(userTags)
.build()
```
### Set Group Tags
Fetch group conversations where the group has specific tags.
```swift theme={null}
let limit = 30
let groupTags = ["tag1"]
let conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: limit)
.setGroupTags(groupTags)
.build()
```
### With Tags
Use `withTags(true)` to include conversation tags in the response. Default is `false`.
```swift theme={null}
var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
.withTags(true)
.build()
```
### Set Tags
Fetch conversations that have specific tags.
```swift theme={null}
let tags = ["pinned", "archived"]
var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
.setTags(tags)
.build()
```
### Include Blocked Users
```swift theme={null}
var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
.includeBlockedUsers(true)
.build()
```
### With Blocked Info
```swift theme={null}
var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
.withBlockedInfo(true)
.build()
```
### Search Conversations
Search conversations by user or group name.
`Conversation & Advanced Search` is available on `Advanced` and `Custom` [plans](https://www.cometchat.com/pricing). Enable it from the [CometChat Dashboard](https://app.cometchat.com) under Chats → Settings → General Configuration.
```swift theme={null}
var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
.setSearchKeyword("Hiking")
.build()
```
### Unread Conversations
`Conversation & Advanced Search` is available on `Advanced` and `Custom` [plans](https://www.cometchat.com/pricing). Enable it from the [CometChat Dashboard](https://app.cometchat.com) under Chats → Settings → General Configuration.
```swift theme={null}
var conversationRequest = ConversationRequest.ConversationRequestBuilder(limit: 50)
.setUnread(true)
.build()
```
### Fetch Conversations
After configuring the builder, call `build()` to create the request, then `fetchNext()` to retrieve conversations. Call `fetchNext()` repeatedly on the same object to paginate.
```swift theme={null}
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 theme={null}
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`](/sdk/reference/entities#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 |
| unreadMessageCount | Unread message count for the conversation |
## Tag Conversation
Use `tagConversation()` to add tags to a conversation.
| Parameter | Description |
| ------------------ | ----------------------------- |
| `conversationWith` | UID or GUID of the user/group |
| `conversationType` | `.user` or `.group` |
| `tags` | Array of tags to add |
```swift theme={null}
let id = "cometchat-uid-1"
let tags = ["pinned"]
CometChat.tagConversation(conversationWith: id, conversationType: .user, tags: tags, onSuccess: { conversation in
print("conversation", conversation)
}, onError: { error in
print("error", error)
})
```
Tags for conversations are one-way. If user A tags a conversation with user B, that tag applies only for user A.
## Retrieve Single Conversation
Use `getConversation()` to fetch a specific conversation.
```swift theme={null}
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 theme={null}
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))")
}
```
## Convert Messages to Conversations
Use `getConversationFromMessage()` to convert a received message into a [`Conversation`](/sdk/reference/entities#conversation) object. Useful for updating your Recent Chats list when receiving real-time messages.
```swift theme={null}
let myConversation = CometChat.getConversationFromMessage(message)
```
When converting a message to a conversation, `unreadMessageCount` and `tags` won't be available. Manage unread counts in your client-side code.
***
## Next Steps
Remove conversations from the logged-in user's list
Listen for incoming messages to update conversation lists in real time
Show real-time typing status in conversations
Track message delivery and read status per conversation