> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# New Chat

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

<Accordion title="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](/ui-kit/android/users), [Groups](/ui-kit/android/groups), [Conversations](/ui-kit/android/conversations), [All Guides](/ui-kit/android/guide-overview) |
</Accordion>

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`.

<Tabs>
  <Tab title="Kotlin">
    ```kotlin ConversationActivity.kt lines theme={null}
    // 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
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java ConversationActivity.java lines theme={null}
    // 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;
    });
    ```
  </Tab>
</Tabs>

### 2. Implement New Chat Screen

Build a tabbed interface with Users and Groups lists.

<Tabs>
  <Tab title="Kotlin">
    ```kotlin NewChatActivity.kt lines theme={null}
    // 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()
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java NewChatActivity.java lines theme={null}
    // 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();
    }
    ```
  </Tab>
</Tabs>

### 3. Handle User or Group Selection

Launch `MessagesActivity` when an item is tapped.

<Tabs>
  <Tab title="Kotlin">
    ```kotlin NewChatActivity.kt lines theme={null}
    // 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)
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java NewChatActivity.java lines theme={null}
    // 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);
    });
    ```
  </Tab>
</Tabs>

### 4. Open the Messages Screen

Read intent extras and configure chat UI.

<Tabs>
  <Tab title="Kotlin">
    ```kotlin MessagesActivity.kt lines theme={null}
    // 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)
        }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java MessagesActivity.java lines theme={null}
    // 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);
      }
    }
    ```
  </Tab>
</Tabs>

## 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

<CardGroup>
  <Card title="Android Sample App (Java)">
    Explore this feature in the CometChat SampleApp:
    [GitHub → SampleApp](https://github.com/cometchat/cometchat-uikit-android/tree/v5/sample-app-java)
  </Card>

  <Card title="Android Sample App (Kotlin)">
    Explore this feature in the CometChat SampleApp:
    [GitHub → SampleApp](https://github.com/cometchat/cometchat-uikit-android/tree/v5/sample-app-kotlin)
  </Card>
</CardGroup>