New Chat

AI Integration Quick Reference

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
Java

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
}

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
Java

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()
}

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
Java

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)
}

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
Java

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)
    }
}

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

User taps the “+” icon → NewChatActivity launches.
Tabs switch between Users and Groups.
Selection triggers MessagesActivity with JSON payload.
Chat UI initializes with the passed user/group.
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`

Overview

Prerequisites

Components

Integration Steps

1. Add Entry Point to New Chat

2. Implement New Chat Screen

3. Handle User or Group Selection

4. Open the Messages Screen

Implementation Flow

Customization Options

Filtering & Edge Cases

Error Handling

Summary / Feature Matrix

Next Steps & Further Reading

Android Sample App (Java)

Android Sample App (Kotlin)

​Overview

​Prerequisites

​Components

​Integration Steps

​1. Add Entry Point to New Chat

​2. Implement New Chat Screen

​3. Handle User or Group Selection

​4. Open the Messages Screen

​Implementation Flow

​Customization Options

​Filtering & Edge Cases

​Error Handling

​Summary / Feature Matrix

​Next Steps & Further Reading

Android Sample App (Java)

Android Sample App (Kotlin)

Overview

Prerequisites

Components

Integration Steps

1. Add Entry Point to New Chat

2. Implement New Chat Screen

3. Handle User or Group Selection

4. Open the Messages Screen

Implementation Flow

Customization Options

Filtering & Edge Cases

Error Handling

Summary / Feature Matrix

Next Steps & Further Reading