New Chat

Enable users to start one-on-one or group chats from a new chat screen with user and group browsing.

AI Agent Component Spec

Field	Value
Package	com.cometchat:chat-uikit-android
Key components	CometChatUsers, CometChatGroups, CometChatMessageList, CometChatMessageComposer, CometChatMessageHeader
Purpose	Enable users to start one-on-one or group chats from a new chat screen with user and group browsing.
Related	Users, Groups, Conversations, All Guides

Enable users to start one-on-one or group chats by integrating CometChat’s New Chat screen (CometChatUsers + CometChatGroups), providing a seamless flow from your conversation list to a specific chat.

Overview

Users can tap the “+” icon in the conversation toolbar or bottom navigation to:

• Browse and search CometChat users.
• Browse and search CometChat groups.
• Select a user or group to launch a chat.

This streamlines contact/group discovery and boosts engagement by reducing friction in starting conversations.

Prerequisites

• Android project with CometChat UIKit Android v5 added in build.gradle.
• CometChat credentials (App ID, Auth Key, Region) initialized.
• Navigation configured: ConversationActivity → NewChatActivity → MessagesActivity.
• Internet and network permissions granted in AndroidManifest.xml.

Components

Component / Class	Role
ConversationActivity	Entry point; hosts “+” icon to launch New Chat screen.
NewChatActivity	Displays tabbed Users/Groups lists.
activity_new_chat.xml	Layout defining TabLayout, CometChatUsers, CometChatGroups.
CometChatUsers	Lists and searches users; exposes setOnItemClick().
CometChatGroups	Lists and searches groups; exposes setOnItemClick().
UsersRequestBuilder	Configures user query filters (e.g. pagination).
GroupsRequestBuilder	Configures group query filters (e.g. pagination).
MessagesActivity	Chat UI for the selected user or group.
activity_messages.xml	Layout for the chat header, message list, and composer.

Integration Steps

1. Add Entry Point to New Chat

Show a “+” icon that launches NewChatActivity.

Kotlin

ConversationActivity.kt

// In ConversationActivity.kt
toolbar.inflateMenu(R.menu.conversation_menu)
toolbar.setOnMenuItemClickListener { item ->
    if (item.itemId == R.id.action_new_chat) {
        startActivity(Intent(this, NewChatActivity::class.java))
        true
    } else false
}

Java

ConversationActivity.java

// In ConversationActivity.java
toolbar.inflateMenu(R.menu.conversation_menu);
toolbar.setOnMenuItemClickListener(item -> {
  if (item.getItemId() == R.id.action_new_chat) {
    startActivity(new Intent(this, NewChatActivity.class));
    return true;
  }
  return false;
});

2. Implement New Chat Screen

Build a tabbed interface with Users and Groups lists.

Kotlin

NewChatActivity.kt

// In NewChatActivity.kt
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_new_chat)

    val tabs = findViewById<TabLayout>(R.id.tabLayout)
    val pager = findViewById<ViewPager2>(R.id.viewPager)
    val adapter = NewChatPagerAdapter(this)
    pager.adapter = adapter
    TabLayoutMediator(tabs, pager) { tab, pos ->
        tab.text = if (pos == 0) "Users" else "Groups"
    }.attach()
}

Java

NewChatActivity.java

// In NewChatActivity.java
@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_new_chat);

  TabLayout tabs = findViewById(R.id.tabLayout);
  ViewPager2 pager = findViewById(R.id.viewPager);
  NewChatPagerAdapter adapter = new NewChatPagerAdapter(this);
  pager.setAdapter(adapter);
  new TabLayoutMediator(tabs, pager, (tab, pos) ->
    tab.setText(pos == 0 ? "Users" : "Groups")
  ).attach();
}

3. Handle User or Group Selection

Launch MessagesActivity when an item is tapped.

Kotlin

NewChatActivity.kt

// In NewChatActivity.kt (Users fragment)
cometChatUsers.setOnItemClick { view, position, user ->
    val intent = Intent(this, MessagesActivity::class.java)
    intent.putExtra("app_user", Gson().toJson(user))
    startActivity(intent)
}

// Similarly for CometChatGroups:
cometChatGroups.setOnItemClick { view, position, group ->
    val intent = Intent(this, MessagesActivity::class.java)
    intent.putExtra("app_group", Gson().toJson(group))
    startActivity(intent)
}

Java

NewChatActivity.java

// In NewChatActivity.java (Users fragment)
cometChatUsers.setOnItemClick((view, position, user) -> {
  Intent i = new Intent(this, MessagesActivity.class);
  i.putExtra("app_user", new Gson().toJson(user));
  startActivity(i);
});

// Similarly for CometChatGroups:
cometChatGroups.setOnItemClick((view, position, group) -> {
  Intent i = new Intent(this, MessagesActivity.class);
  i.putExtra("app_group", new Gson().toJson(group));
  startActivity(i);
});

4. Open the Messages Screen

Read intent extras and configure chat UI.

Kotlin

MessagesActivity.kt

// In MessagesActivity.kt
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_messages)

    val userJson = intent.getStringExtra("app_user")
    val groupJson = intent.getStringExtra("app_group")

    if (userJson != null) {
        val user = Gson().fromJson(userJson, User::class.java)
        messageHeader.setUser(user)
        messageList.setUser(user)
        composer.setUser(user)
    } else if (groupJson != null) {
        val group = Gson().fromJson(groupJson, Group::class.java)
        messageHeader.setGroup(group)
        messageList.setGroup(group)
        composer.setGroup(group)
    }
}

Java

MessagesActivity.java

// In MessagesActivity.java
@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_messages);

  String userJson = getIntent().getStringExtra("app_user");
  String groupJson = getIntent().getStringExtra("app_group");

  if (userJson != null) {
    User user = new Gson().fromJson(userJson, User.class);
    messageHeader.setUser(user);
    messageList.setUser(user);
    composer.setUser(user);
  } else if (groupJson != null) {
    Group group = new Gson().fromJson(groupJson, Group.class);
    messageHeader.setGroup(group);
    messageList.setGroup(group);
    composer.setGroup(group);
  }
}

Implementation Flow

1. User taps the “+” icon → NewChatActivity launches.
2. Tabs switch between Users and Groups.
3. Selection triggers MessagesActivity with JSON payload.
4. Chat UI initializes with the passed user/group.
5. Real-time messaging begins via the UI Kit.

Customization Options

• Styling: Apply cometchatTheme attributes to TabLayout and list items.
• Filtering: Customize UsersRequestBuilder / GroupsRequestBuilder (e.g., hideBlockedUsers(true)).
• Navigation: Replace default MessagesActivity with a custom screen.
• Layout Tweaks: Use android:fitsSystemWindows="true" to avoid overlap.

Filtering & Edge Cases

• Empty States: Built-in empty views in CometChatUsers and CometChatGroups.
• Protected Groups: Prompt for password or disable selection.
• Network Errors: Observe error callbacks and show Snackbar messages.

Error Handling

• Default loading and error states are handled by the UI Kit.
• Attach observers on CometChatUsers / CometChatGroups to handle failures.
• Use Toast or Snackbar for custom error feedback.

Summary / Feature Matrix

Feature	Component / Method	File(s)
Launch New Chat screen	Menu item click in ConversationActivity	ConversationActivity.java
Tabbed lists	TabLayout + ViewPager2	activity_new_chat.xml
List/search users	CometChatUsers + UsersRequestBuilder	activity_new_chat.xml
List/search groups	CometChatGroups + GroupsRequestBuilder	activity_new_chat.xml
Selection handling	setOnItemClick()	NewChatActivity.java
Initialize chat	messageHeader, messageList, composer	MessagesActivity.java, activity_messages.xml

Next Steps & Further Reading

Android Sample App (Java)

Explore this feature in the CometChat SampleApp: GitHub → SampleApp

Android Sample App (Kotlin)

Explore this feature in the CometChat SampleApp: GitHub → SampleApp