Skip to main content
Version: v5

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.

Image

Prerequisites​

Before installing the CometChat UI Kit for Android, you must first create a CometChat application via the CometChat Dashboard. The dashboard provides all the essential chat service components, including:

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

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.

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

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
note

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.

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.

settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
    }
}

ii. Add the CometChat Dependency​

Inside libs.versions.toml, add the CometChat Chat UI Kit version under the [versions] section:

libs.versions.toml
[versions]
cometchat-ui-kit = "5.0.1"
cometchat-calls-sdk = "4.0.8-beta.1"

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

libs.versions.toml
[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:

build.gradle.kts
dependencies {
    implementation(libs.cometchat.ui.kit)

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

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.properties
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, CometChat SDK Method or via the API.

  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.

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 method instead.

info

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 instead of an Auth Key to enhance security and prevent unauthorized access.
MainActivity.kt
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}")
            }
        })
    }
}
note

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.

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.

themes.xml
<style name="YourAppParentTheme" parent="CometChatTheme.DayNight"/>
AndroidManifest.xml
    <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: Applications that need a two-panel layout, such as web-based chat interfaces (e.g., WhatsApp Web, Slack).

Features:

  • Two-panel layout – Displays the conversation list on the left and the active chat window on the right.
  • One-to-one & group conversations – Seamless switching between private and group chats.
  • Multiple conversations – Effortlessly switch between different chat windows.
  • Easy navigation – Intuitive UI for finding and accessing chats quickly.
  • Tap-to-view on mobile – In mobile layouts, tapping a conversation opens the Message View, optimizing space.
  • Real-time updates – Auto-refreshes messages and conversation lists.
  • Message sync – Ensures messages stay updated across all sessions and devices.
Image

Recommended for:

  • Desktop-first applications
  • Apps requiring a rich user experience with seamless navigation
  • Platforms supporting both individual and group messaging
  • Mobile-friendly apps needing a tap-to-open message view

Integrate Conversation List + Message

2️⃣ One-to-One/Group Chat​

Best for: Apps that require a focused, direct messaging experience without a sidebar.

Features:

  • Dedicated chat window – Ideal for one-on-one or group messaging.
  • No conversation list – Users directly enter the chat without navigating through a list.
  • Supports both One-to-One and Group Chats – Easily configurable with minor code modifications.
  • Optimized for mobile – Full-screen chat experience without distractions.
  • Seamless real-time communication – Auto-updates messages for a smooth experience.
  • Ideal for support chat or community-based messaging.
Image

Recommended for:

  • Support chat applications – Direct user-agent communication.
  • Apps focusing on direct messaging – No distractions from other conversations.
  • Community or group chat applications – A structured way to interact in groups.
  • Mobile-first applications – Designed for compact and dedicated messaging experiences.

Integrate One-to-One/Group Chat

3️⃣ Tab-Based Chat Experience​

Best for: Apps that need a structured, multi-feature navigation system for seamless interaction between chats, calls, users, and settings.

Features:

  • Tab Navigation – Easily switch between Chat, Call Logs, Users, and Settings.
  • Dedicated Chat Window – Full-screen messaging experience for focused communication.
  • No Sidebar – Unlike multi-panel UI, this design prioritizes individual interactions.
  • Unified Experience – Users can seamlessly manage conversations, call history, and settings from a single interface.
  • Scalable for future features – Easily extend to include more functionalities such as notifications or contact management.
  • Optimized for both desktop and mobile – Ensures a smooth experience across different screen sizes.
Image

Recommended for:

  • Apps requiring structured navigation – Clearly separate chat, calls, and settings.
  • Multi-feature chat apps – Supporting different functionalities in an organized way.
  • Mobile-first applications – Ideal for apps needing tab-based UI for easy access to features.
  • Support & enterprise chat solutions – Perfect for help desks, business chat platforms, and customer support apps.

Integrate 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 – Fully functional sample applications to accelerate your development.
  • Core Features – Learn about messaging, real-time updates, and other essential capabilities.
  • Components – Utilize prebuilt UI elements or customize them to fit your design.
  • Themes – Adjust colors, fonts, and styles to match your branding.
  • Build Your Own UI – 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: