Conversation List Page

The conversation list page displays all conversations on the current device. The local message database automatically generates the conversation list when messages are created, sorted in reverse chronological order with pinned conversations displayed first.

IMKit provides two implementations for the conversation list page: Activity-based and Fragment-based.

Activity-based: The IMKit SDK provides a default ConversationList Activity that includes a title bar and conversation list view. When the SDK needs to navigate to the conversation list internally, it uses this Activity by default.
Fragment-based: You can integrate the IMKit-provided ConversationList Fragment into a custom Activity to achieve a personalized interface. Note: The custom Activity must be registered with the IMKit SDK to override the default ConversationList Activity.

Conversation List Interface

The conversation list page typically consists of two parts: a title bar and the conversation list.

tip

The default RongConversationListActivity provided by IMKit already includes a title bar implementation. If you build a conversation list page using Fragment, you'll need to implement the title bar functionality yourself.

(width=250)

Title Bar

IMKit implements the title bar functionality only in the default RongConversationListActivity. By default, it displays Conversation List.

Conversation List

The conversation list component displays all conversations in reverse chronological order, with pinned conversations appearing first. A long press on a conversation item triggers a popup menu. IMKit provides default implementations for pinning/unpinning conversations and deleting conversations.

The default conversation item views in the list are created by template classes like PrivateConversationProvider.java. You can extend BaseDataProcessor to aggregate (collapse) or filter which conversation items appear in the list.

tip

If Multi-Device Message Synchronization is enabled, in scenarios like logging in from a new device or reinstalling the app, the offline compensation mechanism can only retrieve one-to-one and group chat messages from the past 1 day (default compensation period, extendable up to 7 days). Conversations beyond this timeframe won't be retrieved through offline compensation. Therefore, the conversation list after offline compensation might differ from the original device's or pre-uninstallation list (this doesn't indicate data loss).

Usage

IMKit provides both Activity and Fragment for creating conversation list pages. RongConversationListActivity is the default implementation. You can choose to use the default Activity directly, extend RongConversationListActivity, or build a custom conversation list Activity using ConversationListFragment.

The IMKit SDK automatically handles clicking a conversation item to navigate to the corresponding chat page.

Launching the Conversation List Page

IMKit offers these methods to launch the conversation list:

Built-in routing: RouteUtils.routeToConversationListActivity(context, title);
Standard launch: startActivity(new Intent(context, RongConversationListActivity.class));

Using RouteUtils

RouteUtils is IMKit's built-in Activity router that encapsulates SDK-internal navigation methods.

tip

If you create a custom conversation list Activity, you must register it with RouteUtils first. Otherwise, RouteUtils will navigate to the SDK's default RongConversationListActivity.

To navigate to the conversation list Activity:

Parameter Description

Parameter	Type	Description
context	Context	Activity context
title	String	Conversation list page title. If empty, defaults to "Conversation List".

Example Code

RouteUtils.routeToConversationListActivity(context, title);

You can construct your own Intent and use Android's default navigation mechanism.

Intent intent = new Intent(context, MyConversationListActivity.class);
context.startActivity(intent);

Extending the Default Conversation List Activity

You can create a custom conversation list Activity by extending RongConversationListActivity to modify its behavior. Remember to register your custom Activity with RouteUtils. After registration, when the SDK needs to navigate to the conversation list, it will use your registered Activity instead. This registration only needs to be done once during the app lifecycle in the main process.

RouteUtils.registerActivity(RouteUtils.RongActivityType.ConversationListActivity, MyConversationListActivity.class);

Building a Custom Conversation List Activity with Fragment

The IMKit SDK provides ConversationListFragment for conversation list implementation. To customize the conversation list page, we recommend extending this Fragment class to build your custom Activity. Note that your custom Activity must be registered with the IMKit SDK to replace the default implementation.

Integrate IMKit's conversation list Fragment into your Activity. Below is an example declaring MyConversationListActivity.

<activity
        android:name=".ui.activity.MyConversationListActivity"
        android:launchMode="singleTop"
        android:screenOrientation="portrait"
        android:windowSoftInputMode="stateHidden|adjustResize">
</activity>

Define the Activity layout. This example uses activity_conversation_list.xml.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:orientation="vertical"
        android:layout_width="match_parent"
        android:layout_height="match_parent">
        <FrameLayout
            android:id="@+id/container" //This container holds the fragment dynamically
            android:layout_width="match_parent"
            android:layout_height="match_parent" />
</LinearLayout>

Extend IMKit's ConversationListFragment to create a subclass like AppConversationListFragment. Use your custom Fragment in MyConversationListActivity's onCreate() method.

class MyConversationListActivity extends FragmentActivity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_conversation_list);

        ConversationListFragment conversationListFragment=new AppConversationListFragment();
        FragmentManager manager = getSupportFragmentManager();
        FragmentTransaction transaction = manager.beginTransaction();
        transaction.replace(R.id.container, conversationListFragment);
        transaction.commit();
    }
}

Register your custom conversation list Activity with RouteUtils to replace IMKit's default implementation. This registration only needs to be done once during the app lifecycle in the main process.

Parameter Description

Parameter	Type	Description
activityType	RongActivityType	IMKit's built-in Activity type enum. Here use `RongActivityType.ConversationListActivity`
class	`Class<? extends Activity>`	Your custom conversation list Activity class.

After registration, when the SDK needs to navigate to the conversation list internally, it will automatically use your registered Activity.

Example Code

RouteUtils.registerActivity(RouteUtils.RongActivityType.ConversationListActivity, MyConversationListActivity.class);

Customization

Modifying Conversation Avatar Shape

Each conversation item in the list displays an avatar icon (different from avatars in the chat message list). Private chats show the other user's avatar, group chats show the group avatar, and aggregated conversations show either a default avatar or one set by the app. IMKit provides global configuration to control avatar styling in the conversation list.

By default, avatars display as rectangles but can be changed to circles. The default avatar size is 48dp*48dp. This modification only takes effect after an avatar is set—without a custom avatar, it defaults to a gray rectangular block. Call this code after app initialization:

   RongConfigCenter.featureConfig().setKitImageEngine(new GlideKitImageEngine() {
            @Override
            public void loadConversationListPortrait(@NonNull Context context, @NonNull String url, @NonNull ImageView imageView, Conversation conversation) {
                Glide.with(context).load(url)
                        .apply(RequestOptions.bitmapTransform(new CircleCrop()))
                        .into(imageView);
            }
        });

To modify avatar styling in the chat message list, see Conversation Page.

Setting Default Conversation Item Load Count

IMKit loads 100 conversation items by default when displaying the conversation list (entering the list, pulling up/down). You can modify this default count.

RongConfigCenter.conversationListConfig().setCountPerPage();

tip

The client's conversation list is generated from local messages, so it only retrieves data locally.

The IMKit SDK shows this default popup when long-pressing a conversation item. You can implement custom handling logic by returning true in the onConversationLongClick() method described in Setting Conversation List Listeners.

(width=250)

Adding Custom Header, Footer, and Empty Views

tip

This feature is available starting from IMKit SDK v5.1.0.

IMKit's ConversationListFragment supports adding custom header, footer, and empty views to the conversation list.

Extend IMKit's ConversationListFragment to create a subclass.
Implement addHeaderView(), addFooterView(), and setEmptyView() methods in the subclass.

Call these methods as needed in the subclass's onViewCreated().

    @Override
    public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
        super.onViewCreated(view, savedInstanceState);
            addHeaderView(view);
            addFooterView(view);
            setEmptyView(view);
    }

   /**
     * @param view Custom header view
     */
    public void addHeaderView(View view) {
        mAdapter.addHeaderView(view);
    }

    /**
     * @param view Custom footer view
     */
    public void addFooterView(View view) {
        mAdapter.addFootView(view);
    }

    /**
     * @param view Custom empty view
     */
    public void setEmptyView(View view) {
        mAdapter.setEmptyView(view);
    }

    /**
     * @param emptyId Layout ID for custom empty view
     */
    public void setEmptyView(@LayoutRes int emptyId) {
        mAdapter.setEmptyView(emptyId);
    }

Showing Network Connection Status Notifications

When the connection drops or reconnects, the SDK displays a status notification bar at the top of both the conversation list and chat pages.

(width=250)

To disable this notification in the conversation list, create an rc_config.xml file in your app's res/values directory and set the rc_is_show_warning_notification variable to false. This XML configuration is a global IMKit setting that affects both conversation and conversation list pages.

Example Code

<bool name="rc_is_show_warning_notification">false</bool>

Clearing Notification Panel Notifications

The IMKit SDK can clear all notifications from the notification panel when opening the conversation list or chat pages. By default, this feature is disabled.

To enable clearing notifications when opening the conversation list, create an rc_config.xml file in your app's res/values directory and set rc_wipe_out_notification_message to true. This is a global setting affecting both pages.

<!--Whether to clear notifications when entering conversation or conversation list page-->
<bool name="rc_wipe_out_notification_message">true</bool>

Customizing UI via XML Resources

IMKit supports modifying the conversation list and item display styles. If the default styles don't meet your needs, you can change backgrounds, font colors, or adjust component layouts by modifying XML resource files.

IMKit Resource File	Location	Description
rc_conversationlist_fragment.xml	res/layout	The container layout for the entire conversation list. Copy the entire content from IMKit's source file to your app's `/res/layout`.
rc_conversationlist_item.xml	res/layout	Layout for individual conversation items. Copy the entire content from IMKit's source file to your app's `/res/layout`.

These XML resources are also available on the Official SDK Download page.

tip

Don't remove views or modify IDs in these XML files, as this may break default SDK logic and cause crashes.

Custom Conversation Item Templates

Below are IMKit's built-in conversation list item templates. To modify how conversation items are displayed, create custom templates and register them.

Template Class	Usage Scenario
PrivateConversationProvider.java	Display template for private conversations.
BaseConversationProvider.java	Base template class. Default template for unmatched conversations.
ConversationListEmptyProvider.java	Empty list template shown when no conversations exist.

Create CustomConversationProvider by extending the base class BaseConversationProvider.

Override isItemViewType() and other methods needing customization.

public class CustomConversationProvider extends BaseConversationProvider {
    @Override
    public boolean isItemViewType(BaseUiConversation item) {
        //Return true if the item matches this template's criteria
        //Example for custom private conversation template
        return item.mCore.getConversationType().equals(Conversation.ConversationType.PRIVATE);
    }

    @Override
    public ViewHolder onCreateViewHolder(ViewGroup parent, int viewType) {
        //Custom handling as needed
        return super.onCreateViewHolder(parent, viewType);
    }

    @Override
    public void bindViewHolder(ViewHolder holder, BaseUiConversation uiConversation, int position, List<BaseUiConversation> list, IViewProviderListener<BaseUiConversation> listener) {
        //Custom handling as needed
        super.bindViewHolder(holder, uiConversation, position, list, listener);
    }
}

//Get template manager
ProviderManager<BaseUiConversation> providerManager = RongConfigCenter.conversationListConfig().getProviderManager();

//Replace SDK's default private conversation template
providerManager.replaceProvider(PrivateConversationProvider.class, new CustomConversationProvider());

//Register a custom template
providerManager.replaceProvider(new CustomSystemConversationProvider());

Additional Customizations

Delete Conversation: IMKit provides default delete functionality via the long-press popup. If this doesn't meet your needs, use IMCenter's delete API.
Get Conversation: The SDK already implements complete conversation retrieval and display logic. Use IMLib APIs only if default behavior is insufficient.
Conversation Draft: IMKit handles draft retrieval, deletion, and page refresh by default. Use IMKit/IMLib APIs only for special requirements.
Pin Conversation: Default pin/unpin functionality with automatic page refresh is provided. Use SDK APIs only for advanced needs.
Custom Conversation List Processing: Filter conversations by type or custom rules for display.

IMLib

IMKit

Global Chat UIKit

push notification

IMLib

IMKit

Global Chat UIKit

CallLib

RTCLib

Chat Server

Chat Server SDK

Audio & Video Server

Conversation List Page

Conversation List Interface​

Title Bar​

Conversation List​

Usage​

Launching the Conversation List Page​

Using RouteUtils​

Parameter Description​

Example Code​

Navigation via Intent​

Extending the Default Conversation List Activity​

Building a Custom Conversation List Activity with Fragment​

Parameter Description​

Example Code​

Customization​

Modifying Conversation Avatar Shape​

Setting Default Conversation Item Load Count​

Customizing Long-press Popup Style​

Adding Custom Header, Footer, and Empty Views​

Showing Network Connection Status Notifications​

Example Code​

Clearing Notification Panel Notifications​

Customizing UI via XML Resources​

Custom Conversation Item Templates​

Additional Customizations​

Conversation List Interface

Title Bar

Conversation List

Usage

Launching the Conversation List Page

Using RouteUtils

Parameter Description

Example Code

Navigation via Intent

Extending the Default Conversation List Activity

Building a Custom Conversation List Activity with Fragment

Parameter Description

Example Code

Customization

Modifying Conversation Avatar Shape

Setting Default Conversation Item Load Count

Customizing Long-press Popup Style

Adding Custom Header, Footer, and Empty Views

Showing Network Connection Status Notifications

Example Code

Clearing Notification Panel Notifications

Customizing UI via XML Resources

Custom Conversation Item Templates

Additional Customizations