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

# Overview

> Build Android chat apps with CometChat SDK v5, including real-time messaging, users, groups, and calling support.

<Warning>
  This is SDK v5 (`5.0.0`). It includes breaking changes from v4 — see the [Migration Guide](/sdk/android/v5/upgrading-from-v4) before upgrading.
</Warning>

This guide demonstrates how to add chat to an Android application. Before you begin, we strongly recommend you read the [Key Concepts](/sdk/android/v5/key-concepts) guide.

#### **I want to integrate with my app**

1. [Get your application keys](./overview#get-your-application-keys)
2. [Add the CometChat dependency](./overview#add-the-cometchat-dependency)
3. [Initialize CometChat](./overview#initialise-cometchat)
4. [Register and Login your user](./overview#register-and-login-your-user)
5. [Integrate Our UI Kits](./overview#integrate-our-ui-kits)

#### **I want to explore a sample app (includes UI)**

Import the app into Android Studio and follow the steps mentioned in the `README.md` file.

[Java Chat App](https://github.com/cometchat-pro/android-java-chat-app/)

[Kotlin Chat App](https://github.com/cometchat-pro/android-kotlin-chat-app)

### Get your Application Keys

[Signup for CometChat](https://app.cometchat.com) and then:

1. Create a new app
2. Head over to the **API Keys** section and note the **Auth Key**, **App ID** & **Region**

<Note>
  Minimum Requirements

  * Android API Level 21
  * Android API level 24 (in case you are using the calls SDKS)
  * Androidx Compatibility
</Note>

### Add the CometChat Dependency

First, add the repository URL to the **project level**`build.gradle` file in the `repositories` block under the `allprojects` section.

<Tabs>
  <Tab title="Groovy">
    ```groovy theme={null}
    allprojects {
      repositories {
        maven {
          url "https://dl.cloudsmith.io/public/cometchat/cometchat/maven/"
        }
      }
    }
    ```
  </Tab>
</Tabs>

Then, add CometChat to the **app level**`build.gradle` file in the `dependencies` section.

<Tabs>
  <Tab title="Groovy">
    ```groovy theme={null}
    dependencies { 
      implementation "com.cometchat:chat-sdk-android:5.0.0"
    }
    ```
  </Tab>
</Tabs>

<Note>
  v2.4+ onwards, Voice & Video Calling functionality has been moved to a separate library. In case you plan to use the calling feature, please add the Calling dependency `implementation 'com.cometchat:calls-sdk-android:4.3.3'` in the dependencies section of the app-level `build.gradle` file.
</Note>

Finally, add the below lines `android` section of the **app level** gradle file

<Tabs>
  <Tab title="Groovy">
    ```groovy theme={null}
    android {
      compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
      }
    }
    ```
  </Tab>
</Tabs>

### Initialise CometChat

The `init()` method initializes the settings required for CometChat. The `init()` method takes the below parameters:

1. appID - You CometChat App ID
2. appSettings - An object of the AppSettings class can be created using the AppSettingsBuilder class. The region field is mandatory and can be set using the `setRegion()` method.

The `AppSettings` class allows you to configure three settings:

* **Region**: The region where you app was created.
* [Presence Subscription](/sdk/android/v5/user-presence): Represents the subscription type for user presence (real-time online/offline status)
* **autoEstablishSocketConnection(boolean value)**: This property takes a boolean value which when set to true informs the SDK to manage the web-socket connection internally. If set to false, it informs the SDK that the web-socket connection will be managed manually. The default value for this parameter is true. For more information on this, please check the Managing Web-Socket connections manually section. The default value for this property is **true.**
* **overrideAdminHost(adminHost: string)**: This method takes the admin URL as input and uses this admin URL instead of the default admin URL. This can be used in case of dedicated deployment of CometChat.
* **overrideClientHost(clientHost: string)**: This method takes the client URL as input and uses this client URL instead of the default client URL. This can be used in case of dedicated deployment of CometChat.

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    String appID = "APP_ID"; // Replace with your App ID
    String region = "REGION"; // Replace with your App Region ("eu" or "us")

    AppSettings appSettings = new AppSettings.AppSettingsBuilder()
        .subscribePresenceForAllUsers()
        .setRegion(region)
        .autoEstablishSocketConnection(true)
        .build();

    CometChat.init(this, appID, appSettings, new CometChat.CallbackListener <String> () {
        @Override
        public void onSuccess(String successMessage) {
            Log.d(TAG, "Initialization completed successfully");
        }

        @Override
        public void onError(CometChatException e) {
            Log.d(TAG, "Initialization failed with exception: " + e.getMessage());
        }
    });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val appID: String = "APP_ID" // Replace with your App ID
    val region: String = "REGION" // Replace with your App Region ("eu" or "us")

    val appSettings = AppSettings.AppSettingsBuilder()
            .subscribePresenceForAllUsers()
            .setRegion(region)
            .autoEstablishSocketConnection(true)
            .build()

    CometChat.init(
        this,
        appID,
        appSettings,
        object : CometChat.CallbackListener<String>() {
            override fun onSuccess(p0: String?) {
                Log.d(TAG, "Initialization completed successfully")
            }

            override fun onError(p0: CometChatException?) {
                Log.d(TAG, "Initialization failed with exception: " + p0?.message)
            }
        }
    )
    ```
  </Tab>
</Tabs>

Make sure you replace the `APP_ID` with your CometChat **App ID** and `region` with your **App Region** in the above code.

### Register and Login your User

Once initialization is successful, you will need to create a user.

To create users on the fly, you can use the `createUser()` method. This method takes a `User` object and the `Auth Key` as input parameters and returns the created `User` object if the request is successful.

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    String authKey = "AUTH_KEY"; // Replace with your App Auth Key
    User user = new User();
    user.setUid("USER_UID"); // Replace with the UID for the user to be created
    user.setName("USER_NAME"); // Replace with the name of the user

    CometChat.createUser(user, authKey, new CometChat.CallbackListener <User> () {
        @Override
        public void onSuccess(User user) {
            Log.d("createUser", user.toString());
        }

        @Override
        public void onError(CometChatException e) {
            Log.e("createUser", e.getMessage());
        }
    });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val authKey = "AUTH_KEY" // Replace with your App Auth Key
    val user = User()
    user.uid = "USER_UID" // Replace with the UID for the user to be created
    user.name = "USER_NAME" // Replace with the name of the user

    CometChat.createUser(user, authKey, object : CometChat.CallbackListener<User>() {
      override fun onSuccess(user: User) {
        Log.d("createUser", user.toString())
      }

      override fun onError(e: CometChatException) {
        Log.e("createUser", e.message)
      }
    })
    ```
  </Tab>
</Tabs>

Make sure that `UID` and `name` are specified as these are mandatory fields to create a user.

Once you have created the user successfully, you will need to log the user into CometChat using the `login()` method.

We recommend you call the CometChat `login()` method once your user logs into your app. The `login()` method needs to be called only once.

<Note>
  This straightforward authentication method is ideal for proof-of-concept (POC) development or during the early stages of application development. For production environments, however, we strongly recommend using an [Auth Token](/sdk/android/v5/authentication-overview#login-using-auth-token) instead of an Auth Key to ensure enhanced security.
</Note>

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    String UID = "user1"; // Replace with the UID of the user to login
    String authKey = "AUTH_KEY"; // Replace with your App Auth Key

    if (CometChat.getLoggedInUser() == null) {
        CometChat.login(UID, authKey, new CometChat.CallbackListener <User> () {
            @Override
            public void onSuccess(User user) {
                Log.d(TAG, "Login Successful : " + user.toString());
            }

            @Override
            public void onError(CometChatException e) {
                Log.d(TAG, "Login failed with exception: " + e.getMessage());
            }
        });
    } else {
        // User already logged in
    }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    val UID: String = "user1" // Replace with the UID of the user to login
    val authKey: String = "AUTH_KEY" // Replace with your App Auth Key

    if (CometChat.getLoggedInUser() == null) {
        CometChat.login(
            UID,
            authKey,
            object : CometChat.CallbackListener<User>() {
                override fun onSuccess(p0: User?) {
                    Log.d(TAG, "Login Successful : " + p0?.toString())
                }

                override fun onError(p0: CometChatException?) {
                    Log.d(TAG, "Login failed with exception: " + p0?.message)
                }
            }
        )
    } else {
        // User already logged in
    }
    ```
  </Tab>
</Tabs>

Make sure you replace the `AUTH_KEY` with your App **Auth Key** in the above code.

The `login()` method returns the `User` object containing all the information of the logged-in user.

<Warning>
  UID can be alphanumeric with underscore and hyphen. Spaces, punctuation and other special characters are not allowed.
</Warning>

### Integrate our UI Kits

* Please refer [Android Java UI Kit](/ui-kit/android/overview) section to integrate Android Java UI Kit inside your app.