Conversations - CometChat Docs

CometChatConversations renders a scrollable list of recent conversations with real-time updates for new messages, typing indicators, read receipts, and user presence.

Where It Fits

CometChatConversations is a list component. It renders recent conversations and emits the selected Conversation via onItemClick. Wire it to CometChatMessageHeader, CometChatMessageList, and CometChatMessageComposer to build a standard chat layout.

Kotlin (XML Views)
Jetpack Compose

activity_chat.xml

<com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations
    android:id="@+id/conversations"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

val conversations = findViewById<CometChatConversations>(R.id.conversations)

conversations.setOnItemClick { conversation ->
    when (val entity = conversation.conversationWith) {
        is User -> navigateToUserChat(entity)
        is Group -> navigateToGroupChat(entity)
    }
}

CometChatConversations(
    modifier = Modifier.fillMaxSize(),
    onItemClick = { conversation ->
        when (val entity = conversation.conversationWith) {
            is User -> navigateToUserChat(entity)
            is Group -> navigateToGroupChat(entity)
        }
    }
)

See the Conversation List + Message View guide for a complete layout.

Quick Start

Kotlin (XML Views)
Jetpack Compose

Add to your layout XML:

<com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations
    android:id="@+id/conversations"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Or programmatically:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(CometChatConversations(this))
}

@Composable
fun ConversationsScreen() {
    CometChatConversations(
        modifier = Modifier.fillMaxSize()
    )
}

Prerequisites: CometChat SDK initialized with CometChatUIKit.init(), a user logged in, and the UI Kit dependency added. Or in a Fragment:

Kotlin (XML Views)
Jetpack Compose

override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
    return CometChatConversations(requireContext())
}

override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
    return ComposeView(requireContext()).apply {
        setContent { CometChatConversations() }
    }
}

Filtering Conversations

Kotlin (XML Views)
Jetpack Compose

Pass a ConversationsRequest.ConversationsRequestBuilder to control what loads:

conversations.setConversationsRequestBuilder(
    ConversationsRequest.ConversationsRequestBuilder()
        .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
        .setLimit(20)
)

CometChatConversations(
    conversationsRequestBuilder = ConversationsRequest.ConversationsRequestBuilder()
        .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
        .setLimit(20)
)

Filter Recipes

Recipe	Builder method
Only user conversations	`.setConversationType(CONVERSATION_TYPE_USER)`
Only group conversations	`.setConversationType(CONVERSATION_TYPE_GROUP)`
Limit per page	`.setLimit(10)`
With tags	`.setTags(listOf("vip")).withTags(true)`
Filter by user tags	`.withUserAndGroupTags(true).setUserTags(listOf("premium"))`
Filter by group tags	`.withUserAndGroupTags(true).setGroupTags(listOf("support"))`

Pass the builder object, not the result of .build(). The component calls .build() internally. Default page size is 30 with infinite scroll.

Actions and Events

Callback Methods

`onItemClick`

Fires when a conversation row is tapped. Primary navigation hook.

Kotlin (XML Views)
Jetpack Compose

conversations.setOnItemClick { conversation ->
    // Navigate to chat screen
}

CometChatConversations(
    onItemClick = { conversation ->
        // Navigate to chat screen
    }
)

Replaces the default item-click behavior. Your custom lambda executes instead of the built-in navigation.

`onItemLongClick`

Fires when a conversation row is long-pressed. Use for additional actions like delete or select.

Kotlin (XML Views)
Jetpack Compose

conversations.setOnItemLongClick { conversation ->
    // Show context menu
}

CometChatConversations(
    onItemLongClick = { conversation ->
        // Show context menu
    }
)

`onBackPress`

Fires when the user presses the back button in the toolbar.

Kotlin (XML Views)
Jetpack Compose

conversations.setOnBackPress {
    finish()
}

CometChatConversations(
    onBackPress = { /* navigate back */ }
)

`onSearchClick`

Fires when the user taps the search icon in the toolbar.

Kotlin (XML Views)
Jetpack Compose

conversations.setOnSearchClick {
    // Open search screen
}

CometChatConversations(
    onSearchClick = { /* open search */ }
)

`onSelection`

Fires when conversations are selected/deselected in multi-select mode.

Kotlin (XML Views)
Jetpack Compose

conversations.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)
conversations.setOnSelection { selectedConversations ->
    updateToolbar(selectedConversations.size)
}

CometChatConversations(
    selectionMode = UIKitConstants.SelectionMode.MULTIPLE,
    onSelection = { selectedConversations ->
        updateToolbar(selectedConversations.size)
    }
)

`onError`

Fires on internal errors (network failure, auth issue, SDK exception).

Kotlin (XML Views)
Jetpack Compose

conversations.setOnError { exception ->
    Log.e("Conversations", "Error: ${exception.message}")
}

CometChatConversations(
    onError = { exception ->
        Log.e("Conversations", "Error: ${exception.message}")
    }
)

`onLoad`

Fires when the list is successfully fetched and loaded.

Kotlin (XML Views)
Jetpack Compose

conversations.setOnLoad { conversations ->
    Log.d("Conversations", "Loaded ${conversations.size}")
}

CometChatConversations(
    onLoad = { conversations ->
        Log.d("Conversations", "Loaded ${conversations.size}")
    }
)

`onEmpty`

Fires when the list is empty after loading.

Kotlin (XML Views)
Jetpack Compose

conversations.setOnEmpty {
    Log.d("Conversations", "No conversations")
}

CometChatConversations(
    onEmpty = { /* no conversations */ }
)

Global Events

The component emits events via CometChatEvents that can be subscribed to from anywhere:

viewModelScope.launch {
    CometChatEvents.conversationEvents.collect { event ->
        when (event) {
            is CometChatConversationEvent.ConversationDeleted -> { /* handle */ }
            is CometChatConversationEvent.ConversationUpdated -> { /* handle */ }
        }
    }
}

SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

SDK Listener	Internal behavior
`onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived`	Moves conversation to top, updates last message and unread count
`onTypingStarted` / `onTypingEnded`	Shows/hides typing indicator in subtitle
`onMessagesDelivered` / `onMessagesRead`	Updates receipt indicators
`onUserOnline` / `onUserOffline`	Updates presence status dot
`onGroupMemberJoined` / `onGroupMemberLeft` / `onGroupMemberKicked` / `onGroupMemberBanned`	Updates group conversation metadata

Functionality

Method (Kotlin XML)	Compose Parameter	Description
`setBackIconVisibility(View.VISIBLE)`	`hideBackIcon = false`	Toggle back button
`setToolbarVisibility(View.GONE)`	`hideToolbar = true`	Toggle toolbar
`setSearchBoxVisibility(View.GONE)`	`hideSearchBox = true`	Toggle search box
`setDisableSoundForMessages(true)`	`disableSoundForMessages = true`	Disable message sounds
`setCustomSoundForMessages(R.raw.sound)`	`customSoundForMessages = R.raw.sound`	Custom message sound
`setSelectionMode(MULTIPLE)`	`selectionMode = MULTIPLE`	Enable selection mode
`setTitle("Chats")`	`title = "Chats"`	Custom toolbar title
`setSearchPlaceholderText("Search...")`	`searchPlaceholderText = "Search..."`	Search placeholder
`setPinConversationOptionVisibility(View.GONE)`	—	Hide the built-in Pin/Unpin conversation option

Custom View Slots

Leading View

Replace the avatar / left section.

Kotlin (XML Views)
Jetpack Compose

conversations.setLeadingView(object : ConversationsViewHolderListener() {
    override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View {
        return ImageView(context).apply {
            layoutParams = ViewGroup.LayoutParams(48.dp, 48.dp)
        }
    }

    override fun bindView(
        context: Context, createdView: View, conversation: Conversation,
        typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder,
        conversations: List<Conversation>, position: Int
    ) {
        val imageView = createdView as ImageView
        // Load avatar image
    }
})

CometChatConversations(
    leadingView = { conversation, typingIndicator ->
        CometChatAvatar(
            imageUrl = conversation.conversationWith?.avatar,
            name = conversation.conversationWith?.name
        )
    }
)

Title View

Replace the name / title text.

Kotlin (XML Views)
Jetpack Compose

conversations.setTitleView(object : ConversationsViewHolderListener() {
    override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View {
        return TextView(context)
    }

    override fun bindView(
        context: Context, createdView: View, conversation: Conversation,
        typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder,
        conversations: List<Conversation>, position: Int
    ) {
        (createdView as TextView).text = conversation.conversationWith?.name ?: ""
    }
})

CometChatConversations(
    titleView = { conversation, _ ->
        Text(
            text = conversation.conversationWith?.name ?: "",
            style = CometChatTheme.typography.heading4Medium
        )
    }
)

Subtitle View

Replace the last message preview.

Kotlin (XML Views)
Jetpack Compose

conversations.setSubtitleView(object : ConversationsViewHolderListener() {
    override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View {
        return TextView(context).apply { maxLines = 1; ellipsize = TextUtils.TruncateAt.END }
    }

    override fun bindView(
        context: Context, createdView: View, conversation: Conversation,
        typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder,
        conversations: List<Conversation>, position: Int
    ) {
        val textView = createdView as TextView
        if (typingIndicator != null) {
            textView.text = "typing..."
        } else {
            textView.text = when (val msg = conversation.lastMessage) {
                is TextMessage -> msg.text
                is MediaMessage -> "📎 ${msg.attachment?.fileExtension ?: "Media"}"
                else -> "New conversation"
            }
        }
    }
})

CometChatConversations(
    subtitleView = { conversation, typingIndicator ->
        val text = if (typingIndicator != null) "typing..." else {
            when (val msg = conversation.lastMessage) {
                is TextMessage -> msg.text ?: ""
                is MediaMessage -> "📎 ${msg.attachment?.fileExtension ?: "Media"}"
                else -> "New conversation"
            }
        }
        Text(text, maxLines = 1, overflow = TextOverflow.Ellipsis)
    }
)

Trailing View

Replace the timestamp / badge / right section.

Kotlin (XML Views)
Jetpack Compose

conversations.setTrailingView(object : ConversationsViewHolderListener() {
    override fun createView(context: Context, binding: CometchatConversationsListItemsBinding): View {
        return TextView(context)
    }

    override fun bindView(
        context: Context, createdView: View, conversation: Conversation,
        typingIndicator: TypingIndicator?, holder: RecyclerView.ViewHolder,
        conversations: List<Conversation>, position: Int
    ) {
        (createdView as TextView).text = "${conversation.unreadMessageCount} unread"
    }
})

CometChatConversations(
    trailingView = { conversation, _ ->
        if (conversation.unreadMessageCount > 0) {
            Badge { Text("${conversation.unreadMessageCount}") }
        }
    }
)

State Views

Kotlin (XML Views)
Jetpack Compose

conversations.setEmptyView(customEmptyView)
conversations.setErrorView(customErrorView)
conversations.setLoadingView(customLoadingView)

CometChatConversations(
    emptyView = { Text("No conversations yet") },
    errorView = { onRetry -> Button(onClick = onRetry) { Text("Retry") } },
    loadingView = { CircularProgressIndicator() }
)

Kotlin (XML Views)
Jetpack Compose

conversations.setOverflowMenu(ImageButton(context).apply {
    setImageResource(R.drawable.ic_filter)
    setOnClickListener { /* show filter */ }
})

CometChatConversations(
    overflowMenu = {
        IconButton(onClick = { /* show filter */ }) {
            Icon(painterResource(R.drawable.ic_filter), "Filter")
        }
    }
)

Kotlin (XML Views)
Jetpack Compose

// Replace all options
conversations.setOptions { context, conversation ->
    listOf(
        CometChatPopupMenu.MenuItem(id = "archive", name = "Archive", onClick = { /* ... */ }),
        CometChatPopupMenu.MenuItem(id = "mute", name = "Mute", onClick = { /* ... */ })
    )
}

// Append to defaults
conversations.setAddOptions { context, conversation ->
    listOf(
        CometChatPopupMenu.MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ })
    )
}

CometChatConversations(
    options = { context, conversation ->
        listOf(
            MenuItem(id = "archive", name = "Archive", onClick = { /* ... */ }),
            MenuItem(id = "mute", name = "Mute", onClick = { /* ... */ })
        )
    },
    addOptions = { context, conversation ->
        listOf(MenuItem(id = "pin", name = "Pin", onClick = { /* ... */ }))
    }
)

Built-in Pin Conversation Option

When the Pin Conversation feature is enabled for your app (CometChatUIKit.isPinConversationEnabled()), the long-press menu automatically includes Pin conversation / Unpin conversation — no wiring needed. Pinning applies immediately with a toast; unpinning asks for confirmation first. Pinned conversations display a pin indicator next to the timestamp and stay at the top of the list, holding their position even as new messages arrive in other chats. Hide the option with setPinConversationOptionVisibility(View.GONE). To render a pinned-only list, pass a request builder with the pinned filter — see Pin A Conversation (SDK):

conversations.setConversationsRequestBuilder(
    ConversationsRequest.ConversationsRequestBuilder().setPinnedBy("system,me")
)

Common Patterns

Minimal list — hide all chrome

Kotlin (XML Views)
Jetpack Compose

conversations.setToolbarVisibility(View.GONE)
conversations.setSearchBoxVisibility(View.GONE)

CometChatConversations(
    hideToolbar = true,
    hideSearchBox = true
)

Users-only conversations

Kotlin (XML Views)
Jetpack Compose

conversations.setConversationsRequestBuilder(
    ConversationsRequest.ConversationsRequestBuilder()
        .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
)

CometChatConversations(
    conversationsRequestBuilder = ConversationsRequest.ConversationsRequestBuilder()
        .setConversationType(CometChatConstants.CONVERSATION_TYPE_USER)
)

Custom date formatting

Kotlin (XML Views)
Jetpack Compose

conversations.setDateTimeFormatter(object : DateTimeFormatterCallback {
    override fun today(timestamp: Long) = "Today"
    override fun yesterday(timestamp: Long) = "Yesterday"
    override fun otherDays(timestamp: Long) = SimpleDateFormat("MMM d", Locale.getDefault()).format(Date(timestamp))
    override fun time(timestamp: Long) = SimpleDateFormat("h:mm a", Locale.getDefault()).format(Date(timestamp))
    override fun minutes(diff: Long, timestamp: Long) = "${diff}m ago"
    override fun hours(diff: Long, timestamp: Long) = "${diff}h ago"
    override fun lastWeek(timestamp: Long) = "Last week"
})

CometChatConversations(
    dateTimeFormatter = object : DateTimeFormatterCallback {
        override fun today(timestamp: Long) = "Today"
        override fun yesterday(timestamp: Long) = "Yesterday"
        override fun otherDays(timestamp: Long) = SimpleDateFormat("MMM d", Locale.getDefault()).format(Date(timestamp))
        override fun time(timestamp: Long) = SimpleDateFormat("h:mm a", Locale.getDefault()).format(Date(timestamp))
        override fun minutes(diff: Long, timestamp: Long) = "${diff}m ago"
        override fun hours(diff: Long, timestamp: Long) = "${diff}h ago"
        override fun lastWeek(timestamp: Long) = "Last week"
    }
)

Advanced Methods

Programmatic Selection

Kotlin (XML Views)
Jetpack Compose

// Enable selection
conversations.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE)

// Select a conversation
conversations.selectConversation(conversation, UIKitConstants.SelectionMode.MULTIPLE)

// Get selected
val selected = conversations.getSelectedConversations()

// Clear
conversations.clearSelection()

Selection is managed via the selectionMode and onSelection parameters. The component handles selection state internally.

ViewModel Access

val factory = CometChatConversationsViewModelFactory(
    repository = MyCustomRepository() // optional
)
val viewModel = ViewModelProvider(this, factory)
    .get(CometChatConversationsViewModel::class.java)

Kotlin (XML Views)
Jetpack Compose

conversations.setViewModel(viewModel)

CometChatConversations(
    conversationsViewModel = viewModel
)

See ViewModel & Data for ListOperations, state observation, and custom repositories.

Style

Kotlin (XML Views)
Jetpack Compose

Define a custom style in themes.xml:

themes.xml

<style name="CustomConversationsStyle" parent="CometChatConversationsStyle">
    <item name="cometchatConversationsAvatarStyle">@style/CustomAvatarStyle</item>
    <item name="cometchatConversationsBadgeStyle">@style/CustomBadgeStyle</item>
    <item name="cometchatConversationsReceiptStyle">@style/CustomReceiptStyle</item>
    <item name="cometchatConversationsDateStyle">@style/CustomDateStyle</item>
</style>

<style name="AppTheme" parent="CometChatTheme.DayNight">
    <item name="cometchatConversationsStyle">@style/CustomConversationsStyle</item>
</style>

CometChatConversations(
    style = CometChatConversationsStyle.default().copy(
        backgroundColor = Color(0xFFF5F5F5),
        titleTextColor = Color(0xFF141414),
        searchBoxStyle = CometChatSearchBoxStyle.default().copy(
            backgroundColor = Color(0xFFFFFFFF)
        ),
        itemStyle = CometChatConversationsItemStyle.default().copy(
            backgroundColor = Color.White,
            titleTextColor = Color(0xFF141414),
            subtitleTextColor = Color(0xFF727272),
            avatarStyle = CometChatAvatarStyle.default().copy(cornerRadius = 12.dp),
            badgeStyle = CometChatBadgeStyle.default().copy(backgroundColor = Color(0xFFF76808)),
            dateStyle = CometChatDateStyle.default().copy(textColor = Color(0xFFA1A1A1)),
            receiptStyle = CometChatReceiptStyle.default().copy(),
            statusIndicatorStyle = CometChatStatusIndicatorStyle.default().copy(),
            typingIndicatorStyle = CometChatTypingIndicatorStyle.default().copy()
        )
    )
)

Style Properties

Property	Description
`backgroundColor`	List background color
`titleTextColor`	Toolbar title color
`searchBoxStyle`	Search box appearance
`itemStyle.backgroundColor`	Row background
`itemStyle.selectedBackgroundColor`	Selected row background
`itemStyle.titleTextColor`	Conversation name color
`itemStyle.subtitleTextColor`	Last message preview color
`itemStyle.separatorColor`	Row separator color
`itemStyle.avatarStyle`	Avatar appearance
`itemStyle.badgeStyle`	Unread badge appearance
`itemStyle.dateStyle`	Timestamp appearance
`itemStyle.receiptStyle`	Read receipt icons
`itemStyle.statusIndicatorStyle`	Online/offline indicator
`itemStyle.typingIndicatorStyle`	Typing indicator text
`itemStyle.mentionStyle`	Mention highlight style

See Component Styling for the full reference.

Next Steps

Conversation List + Message View

Build a full chat layout with this component

Component Styling

Detailed styling reference with screenshots

ViewModel & Data

Custom ViewModels, repositories, and ListOperations

View Slots

Replace specific UI regions across all components

​Where It Fits

​Quick Start

​Filtering Conversations

​Filter Recipes

​Actions and Events

​Callback Methods

​onItemClick

​onItemLongClick

​onBackPress

​onSearchClick

​onSelection

​onError

​onLoad

​onEmpty

​Global Events

​SDK Events (Real-Time, Automatic)

​Functionality

​Custom View Slots

​Leading View

​Title View

​Subtitle View

​Trailing View

​State Views

​Overflow Menu

​Menu Options

​Built-in Pin Conversation Option

​Common Patterns

​Minimal list — hide all chrome

​Users-only conversations

​Custom date formatting

​Advanced Methods

​Programmatic Selection

​ViewModel Access

​Style

​Style Properties

​Next Steps

Conversation List + Message View

Component Styling

ViewModel & Data

View Slots

Where It Fits

Quick Start

Filtering Conversations

Filter Recipes

Actions and Events

Callback Methods

`onItemClick`

`onItemLongClick`

`onBackPress`

`onSearchClick`

`onSelection`

`onError`

`onLoad`

`onEmpty`

Global Events

SDK Events (Real-Time, Automatic)

Functionality

Custom View Slots

Leading View

Title View

Subtitle View

Trailing View

State Views

Overflow Menu

Menu Options

Built-in Pin Conversation Option

Common Patterns

Minimal list — hide all chrome

Users-only conversations

Custom date formatting

Advanced Methods

Programmatic Selection

ViewModel Access

Style

Style Properties

Next Steps