> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-feature-react-native-sdk-quotedmessage-a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started With CometChat Android UI Kit

The **CometChat UI Kit for Android** streamlines the integration of in-app chat functionality by providing a **comprehensive set of prebuilt UI components**. It offers seamless **theming options**, including **light and dark modes**, customizable fonts, colors, and extensive styling capabilities.

With built-in support for **one-to-one and group conversations**, developers can efficiently enable chat features within their applications. Follow this guide to **quickly integrate chat functionality** using the CometChat Android UI Kit.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-feature-react-native-sdk-quotedmessage-a/Zp9d87qbHHZCI7d4/images/d2559907-intro_android_screens-3e86359342605c94dc912604de8f6617.png?fit=max&auto=format&n=Zp9d87qbHHZCI7d4&q=85&s=a2097ca77e8abe0cb60ae6626f4450bb" width="1440" height="833" data-path="images/d2559907-intro_android_screens-3e86359342605c94dc912604de8f6617.png" />
</Frame>

***

***

## **Prerequisites**

Before installing the **CometChat UI Kit for Android**, you must first **create a CometChat application** via the **[CometChat Dashboard](https://app.cometchat.com/)**. The dashboard provides all the essential chat service components, including:

* **User Management**
* **Group Chat & Messaging**
* **Voice & Video Calling**
* **Real-time Notifications**

<Info>
  To initialize the **UI Kit**, you will need the following credentials from your **CometChat application**:

  1. **App ID**
  2. **Auth Key**
  3. **Region**

  Ensure you have these details ready before proceeding with the installation and configuration.
</Info>

***

## **Register & Set Up CometChat**

Follow these steps to **register on CometChat** and **set up your development environment**.

### **Step 1: Register on CometChat**

To use **CometChat UI Kit**, you first need to register on the **CometChat Dashboard**.

🔗 **[Click here to Sign Up](https://app.cometchat.com/login)**

### **Step 2: Get Your Application Keys**

After registering, create a **new app** and retrieve your **authentication details**:

1. Navigate to **Application**, then select the **Credentials** section.

2. Note down the following keys:

   * **App ID**
   * **Auth Key**
   * **Region**

<Info>
  Each CometChat application can be integrated with a **single client app**. Users within the same application can communicate across multiple platforms, including **web and mobile**.
</Info>

### **Step 3: Set Up Your Development Environment**

Ensure your system meets the following **prerequisites** before proceeding with integration.

**System Requirements:**

* **Android Studio** installed on your machine.
* An **Android emulator or physical device** running Android 6.0 or higher.
* **Java 8 or higher** installed.
* **Gradle plugin 4.0.1 or later** installed.

***

## **Getting Started**

### **Step 1: Create an Android Project**

1. Open **Android Studio** and start a **new project**.
2. Choose **Empty Activity** as the project template.
3. Enter a project name and choose **Java** or **Kotlin** as the language.
4. Set **minimum API level** to **21 or higher**.

***

### **Step 2: Install Dependencies**

To integrate CometChat into your Android project, add the required dependencies to your **Gradle configuration**.

#### **i. Add the CometChat Repository**

To integrate CometChat into your Android project, you need to add the CometChat repository to your project-level `settings.gradle` or `settings.gradle.kts` file. Follow the steps below based on your project configuration.

<Tabs>
  <Tab title="Kotlin">
    ```gradle settings.gradle.kts theme={null}
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
            maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
        }
    }
    ```
  </Tab>

  <Tab title="Groovy">
    ```gradle settings.gradle theme={null}
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
            maven{
                url "https://dl.cloudsmith.io/public/cometchat/cometchat/maven/"
            }
        }
    }
    ```
  </Tab>
</Tabs>

#### **ii. Add the CometChat Dependency**

<Tabs>
  <Tab title="Version Catalog (libs.versions.toml)">
    Inside `libs.versions.toml`, add the CometChat Chat UI Kit version under the `[versions]` section:

    ```toml libs.versions.toml theme={null}
    [versions]
    cometchat-ui-kit = "5.2.2"
    cometchat-calls-sdk = "4.3.1"
    ```

    Under the `[libraries]` section, define the library and reference the version:

    ```toml libs.versions.toml theme={null}
    [libraries]
    cometchat-ui-kit = { module = "com.cometchat:chat-uikit-android", version.ref = "cometchat-ui-kit" }
    cometchat-calls-sdk = { module = "com.cometchat:calls-sdk-android", version.ref = "cometchat-calls-sdk" }
    ```

    Now, in your app-level `build.gradle.kts` file, add the dependency using libs from Version Catalogs:

    ```gradle build.gradle.kts theme={null}
    dependencies {
        implementation(libs.cometchat.ui.kit)

        // (Optional) Include if using voice/video calling features
        implementation(libs.cometchat.calls.sdk)
    }
    ```
  </Tab>

  <Tab title="Gradle (build.gradle)">
    Open the **app level** `build.gradle` file and add the following dependency to fetch the chat UI kit into your project.

    ```gradle build.gradle theme={null}
    dependencies {
        // CometChat UIKit
        implementation 'com.cometchat:chat-uikit-android:5.2.2'

        // (Optional) Include this if your app uses voice/video calling features
        implementation 'com.cometchat:calls-sdk-android:4.3.1'
    }
    ```
  </Tab>
</Tabs>

#### **iii. Add AndroidX Support**

The Jetifier tool helps migrate legacy support libraries to AndroidX.

Open the gradle.properties file and verify if the specified line is present. If not, add it accordingly.

```gradle gradle.properties theme={null}
android.enableJetifier=true
```

***

### **Step 3: Initialize & Login to CometChat UI Kit**

To authenticate a user, you need a **`UID`**. You can either:

1. **Create new users** on the **[CometChat Dashboard](https://app.cometchat.com)**, **[CometChat SDK Method](/ui-kit/android/methods#create-user)** or **[via the API](https://api-explorer.cometchat.com/reference/creates-user)**.

2. **Use pre-generated test users**:

   * `cometchat-uid-1`
   * `cometchat-uid-2`
   * `cometchat-uid-3`
   * `cometchat-uid-4`
   * `cometchat-uid-5`

The **Login** method returns a **User object** containing all relevant details of the logged-in user.

***

<Note>
  **Auth Key Usage**

  The **Auth Key** is an **optional property** of the `UIKitSettings` class. It is primarily recommended for **proof-of-concept (POC) development** or **early-stage application development**.

  For secure authentication, use the [`Auth Token`](/ui-kit/android/methods#login-using-auth-token) method instead.
</Note>

***

<Note>
  **Security Best Practices**

  * The **Auth Key** method is recommended for **proof-of-concept (POC) development** and early-stage testing.
  * For **production environments**, it is strongly advised to use an **[Auth Token](/ui-kit/android/methods#login-using-auth-token)** instead of an **Auth Key** to enhance security and prevent unauthorized access.
</Note>

<Tabs>
  <Tab title="Kotlin">
    ```kotlin MainActivity.kt theme={null}
    import android.os.Bundle
    import android.util.Log
    import androidx.activity.ComponentActivity
    import androidx.activity.enableEdgeToEdge
    import com.cometchat.chat.core.CometChat
    import com.cometchat.chat.exceptions.CometChatException
    import com.cometchat.chat.models.User
    import com.cometchat.chatuikit.shared.cometchatuikit.CometChatUIKit
    import com.cometchat.chatuikit.shared.cometchatuikit.UIKitSettings

    class MainActivity : ComponentActivity() {

        private val TAG = "MainActivity"

        private val appID = "APP_ID" // Replace with your App ID
        private val region = "REGION" // Replace with your App Region
        private val authKey = "AUTH_KEY" // Replace with your Auth Key or leave blank if you are authenticating using Auth Token

        private val uiKitSettings = UIKitSettings.UIKitSettingsBuilder()
            .setRegion(region)
            .setAppId(appID)
            .setAuthKey(authKey)
            .subscribePresenceForAllUsers()
            .build()

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            enableEdgeToEdge()

            CometChatUIKit.init(this, uiKitSettings, object : CometChat.CallbackListener<String?>() {
                override fun onSuccess(successString: String?) {

                    Log.d(TAG, "Initialization completed successfully")

                    loginUser()
                }

                override fun onError(e: CometChatException?) {}
            })
        }

        private fun loginUser() {
            CometChatUIKit.login("cometchat-uid-1", object : CometChat.CallbackListener<User>() {
                override fun onSuccess(user: User) {

                    // ✅ Option 1: Launch One-to-One or Group Chat Screen
                    // val intent = Intent(this@MainActivity, MessageActivity::class.java)
                    // intent.putExtra("uid", "cometchat-uid-1")
                    // startActivity(intent)

                    // ✅ Option 2: Launch Conversation List + Message View (Split-Screen Style)
                    // startActivity(Intent(this@MainActivity, ConversationActivity::class.java))

                    // ✅ Option 3: Launch Tab-Based Chat Experience (Chats, Calls, Users, Groups)
                    // startActivity(Intent(this@MainActivity, TabbedActivity::class.java))
                }

                override fun onError(e: CometChatException) {
                    // Handle login failure (e.g. show error message or retry)
                    Log.e("Login", "Login failed: ${e.message}")
                }
            })
        }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java MainActivity.java theme={null}
    import android.content.Intent;
    import android.os.Bundle;
    import android.util.Log;
    import androidx.activity.ComponentActivity;
    import com.cometchat.chat.core.CometChat;
    import com.cometchat.chat.exceptions.CometChatException;
    import com.cometchat.chat.models.User;
    import com.cometchat.chatuikit.shared.cometchatuikit.CometChatUIKit;
    import com.cometchat.chatuikit.shared.cometchatuikit.UIKitSettings;

    public class MainActivity extends ComponentActivity {

        private static final String TAG = "MainActivity";

        private final String appID = "APP_ID"; // Replace with your App ID
        private final String region = "REGION"; // Replace with your App Region
        private final String authKey = "AUTH_KEY"; // Replace with your Auth Key

        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            getWindow().setDecorFitsSystemWindows(false); // Equivalent to enableEdgeToEdge()

            UIKitSettings uiKitSettings = new UIKitSettings.UIKitSettingsBuilder()
                    .setRegion(region)
                    .setAppId(appID)
                    .setAuthKey(authKey)
                    .subscribePresenceForAllUsers()
                    .build();

            CometChatUIKit.init(this, uiKitSettings, new CometChat.CallbackListener<String>() {
                @Override
                public void onSuccess(String success) {
                    Log.d(TAG, "Initialization completed successfully");
                    loginUser();
                }

                @Override
                public void onError(CometChatException e) {
                    Log.e(TAG, "Initialization failed: " + (e != null ? e.getMessage() : "Unknown error"));
                }
            });
        }

        private void loginUser() {
            CometChatUIKit.login("cometchat-uid-1", new CometChat.CallbackListener<User>() {
                @Override
                public void onSuccess(User user) {
                    Log.d(TAG, "Login successful for user: " + user.getUid());

                    // ✅ Option 1: Launch One-to-One or Group Chat Screen
                    // Intent intent = new Intent(MainActivity.this, MessageActivity.class);
                    // intent.putExtra("uid", "cometchat-uid-1");
                    // startActivity(intent);

                    // ✅ Option 2: Launch Conversation List + Message View
                    // startActivity(new Intent(MainActivity.this, ConversationActivity.class));

                    // ✅ Option 3: Launch Tab-Based Chat Experience (Chats, Calls, Users, Groups)
                    // startActivity(new Intent(MainActivity.this, TabbedActivity.class));
                }

                @Override
                public void onError(CometChatException e) {
                    Log.e("Login", "Login failed: " + (e != null ? e.getMessage() : "Unknown error"));
                }
            });
        }
    }
    ```
  </Tab>
</Tabs>

<Info>
  Ensure you replace the following placeholders with your actual CometChat credentials:

  * APP\_ID → Your CometChat App ID
  * AUTH\_KEY → Your CometChat Auth Key
  * REGION → Your App Region

  These values are required for proper authentication and seamless integration.
</Info>

***

### **Step 4: Set Up Global Theme**

To customize component styling across your application in one place, you need to set up the **CometChat Theme**.

Use the `CometChatTheme.DayNight` style, which is built on `Theme.MaterialComponents.DayNight.NoActionBar`.

**Apply the Theme**

Set `CometChatTheme.DayNight` as the parent theme for your application in the `themes.xml` file.

```xml themes.xml theme={null}
<style name="YourAppParentTheme" parent="CometChatTheme.DayNight"/>
```

```xml AndroidManifest.xml theme={null}
    <application
        android:theme="@style/YourAppParentTheme"
        ...
        ...
    >

    </application>
```

***

### **Step 5: Choose a Chat Experience**

Integrate a conversation view that suits your application's **UX requirements**. Below are the available options:

***

### **1️⃣ Conversation List + Message View**

**Best for:** Android apps needing a **fluid tap-to-open messaging experience** while managing multiple conversations.

**Highlights:**

* **Compact UI** – Single-screen layout for mobile; tap a conversation to open the message view.
* **One-to-One & Group Chats** – Handle private and group conversations natively.
* **Session Persistence** – Messages and read states sync across devices.
* **Real-Time Messaging** – Seamless updates for both message view and conversation list.
* **Smooth Navigation** – Intuitive stack-based flow using `FragmentManager` or Jetpack Navigation.
* **Lightweight & performant** – Designed for mobile responsiveness and low memory footprint.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-feature-react-native-sdk-quotedmessage-a/yDKVamMkf61gj3YR/images/e395dc74-chat_experience_sidebar_message-79d0b141acb1aea61bae33f121988572.png?fit=max&auto=format&n=yDKVamMkf61gj3YR&q=85&s=2d3bb8ae07ad8540f79274d3ef07ccac" width="1440" height="833" data-path="images/e395dc74-chat_experience_sidebar_message-79d0b141acb1aea61bae33f121988572.png" />
</Frame>

**Use When:**

* You need **mobile-friendly navigation** between multiple chats.
* Your app supports **both 1:1 and group messaging**.
* You want a **clean switch between list and message view** without sidebars.

[Integrate Conversation List + Message View](./android-conversation)

***

### **2️⃣ One-to-One / Group Chat**

**Best for:** Use cases where users jump **directly into a chat** — no list, just the conversation.

**Highlights:**

* **Single chat screen** – Loads a specific user/group chat without navigating a list.
* **Ideal for contextual use-cases** – Support chats, direct messages, or contextual onboarding flows.
* **Lightweight** – Minimal UI, reduced code complexity.
* **Full-screen messaging** – Immersive, distraction-free conversation experience.
* **Flexible setup** – Accepts pre-fetched user/group object or ID for quick launch.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-feature-react-native-sdk-quotedmessage-a/195oxTVcmj5zqz-a/images/c401197a-chat_experience_one_on_one-5b74b8c178c83ecb0a8879e898fcb854.png?fit=max&auto=format&n=195oxTVcmj5zqz-a&q=85&s=f976b52990f4870d816c8f21eec057bc" width="1440" height="833" data-path="images/c401197a-chat_experience_one_on_one-5b74b8c178c83ecb0a8879e898fcb854.png" />
</Frame>

**Use When:**

* Your flow starts with **a specific contact or ticket** (e.g., customer support).
* You want a **no-frills, clean chat screen**.
* Perfect for **helpdesks, dating apps, or onboarding flows**.

[Integrate One-to-One / Group Chat](./android-one-to-one-chat)

***

### **3️⃣ Tab-Based Messaging UI (All-in-One)**

**Best for:** Android apps with **multi-feature navigation** like chats, calls, contacts, and settings — all from a single entry point.

**Highlights:**

* **Bottom Navigation** – Use Android’s `BottomNavigationView` for fast switching between features.
* **Dedicated Fragments** – Each tab (Chats, Calls, Users, Settings) has its own optimized view.
* **No Sidebar** – Mobile-first, stack-based design, ideal for small screens.
* **Modular & Extensible** – Add more tabs (e.g., Notifications, Favorites) as needed.
* **Perfect for SuperApps** – Unified chat, VoIP, and user management in one interface.
* **Responsive Layouts** – Adjusts to different screen sizes and orientations.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-feature-react-native-sdk-quotedmessage-a/494NzpIb6o8839I0/images/7e8b813d-chat_experience_full_tab_based-28115d603d38f5bbfbfe170739aa478c.png?fit=max&auto=format&n=494NzpIb6o8839I0&q=85&s=25aa490826773d7edd6b97479484d6fa" width="1440" height="833" data-path="images/7e8b813d-chat_experience_full_tab_based-28115d603d38f5bbfbfe170739aa478c.png" />
</Frame>

**Use When:**

* You want a **multi-functional chat app** in one interface.
* Your users need to **navigate easily between modules**.
* Ideal for **support, enterprise, or social apps**.

[Integrate Tab-Based Chat](./android-tab-based-chat)

***

## **Build Your Own Chat Experience**

**Best for:** Developers who need complete control over their chat interface, allowing customization of components, themes, and features to align with their app’s design and functionality. Whether you're enhancing an existing chat experience or building from scratch, this approach provides the flexibility to tailor every aspect to your needs.

**Recommended for:**

* Apps that require **a fully customized chat experience**.
* Developers who want to **extend functionalities and modify UI components**.
* Businesses integrating chat seamlessly into **existing platforms**.

**Key Areas to Explore:**

* **[Android Sample App](https://github.com/cometchat/cometchat-uikit-android/tree/v5/sample-app-kotlin)** – Fully functional sample applications to accelerate your development.
* **[Core Features](./core-features)** – Learn about messaging, real-time updates, and other essential capabilities.
* **[Components](./components-overview)** – Utilize prebuilt UI elements or customize them to fit your design.
* **[Themes](./theme)** – Adjust colors, fonts, and styles to match your branding.
* **[Build Your Own UI](./../../../sdk/javascript/overview)** – Prefer a custom UI over our UI Kits? Explore our SDKs to create a tailored chat experience.

***

## **Next Steps**

Now that you’ve selected your **chat experience**, proceed to the **integration guide**:

* **[Integrate Conversation List + Message](/ui-kit/android/android-conversation)**
* **[Integrate One-to-One Chat](/ui-kit/android/android-one-to-one-chat)**
* **[Integrate Tab-Based Chat](/ui-kit/android/android-tab-based-chat)**
* **[Advanced Customizations](/ui-kit/android/theme-introduction)**

***