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

# Setup

> Install and initialize the CometChat Android SDK with app credentials, region, dependencies, and basic project setup.

<Accordion title="AI Integration Quick Reference">
  ```kotlin theme={null}
  // 1. Add dependency to build.gradle
  implementation "com.cometchat:chat-sdk-android:4.2.0"

  // 2. Initialize (run once at app start)
  val appSettings = AppSettings.AppSettingsBuilder()
      .subscribePresenceForAllUsers()
      .setRegion("REGION")
      .build()
  CometChat.init(context, "APP_ID", appSettings, callback)

  // 3. Login user
  CometChat.login("UID", "AUTH_KEY", callback)  // Dev only
  ```

  **Required Credentials:** App ID, Region, Auth Key (dev) or Auth Token (prod)\
  **Get from:** [CometChat Dashboard](https://app.cometchat.com) → Your App → API & Auth Keys
</Accordion>

## Prerequisites

| Requirement                        | Minimum Version |
| ---------------------------------- | --------------- |
| Android API Level                  | 21              |
| Android API Level (with Calls SDK) | 24              |
| Java                               | 8               |
| AndroidX                           | Required        |

Get your credentials from the [CometChat Dashboard](https://app.cometchat.com):

* App ID
* Region
* Auth Key (for development)

<Warning>
  **Auth Key** is for development/testing only. In production, generate **Auth Tokens** on your server using the REST API and pass them to the client. Never expose Auth Keys in production client code.
</Warning>

## Add the CometChat Dependency

### Gradle

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

<Tabs>
  <Tab title="Groovy">
    ```java 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">
    ```java theme={null}
    dependencies {
      implementation "com.cometchat:chat-sdk-android:4.2.0"
    }
    ```
  </Tab>
</Tabs>

<Note>
  If you plan to use the calling feature, 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 following lines to the `android` section of the **app level** gradle file.

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

## Initialize CometChat

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

1. `appID` - Your CometChat App ID
2. `appSettings` - An object of the `AppSettings` class 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 the following settings:

* **Region**: The region where your app was created.
* **[Presence Subscription](/sdk/android/user-presence)**: Represents the subscription type for user presence (real-time online/offline status).
* **autoEstablishSocketConnection(boolean value)**: When set to `true`, the SDK manages the WebSocket connection internally. When set to `false`, you must manage the WebSocket connection manually. The default value is `true`. For more information, see the Managing Web-Socket connections manually section.
* **overrideAdminHost(adminHost: string)**: Takes the admin URL as input and uses it instead of the default admin URL. This is useful for dedicated deployments of CometChat.
* **overrideClientHost(clientHost: string)**: Takes the client URL as input and uses it instead of the default client URL. This is useful for dedicated deployments of CometChat.

We recommend calling the `init()` method on app startup.

<Warning>
  `CometChat.init()` must be called before any other SDK method. Calling `login()`, `sendMessage()`, or registering listeners before `init()` will fail.
</Warning>

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    private String appID = "APP_ID"; // Replace with your App ID
    private 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")

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

    CometChat.init(this,appID,appSetting, 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>

| Parameter    | Description                          |
| ------------ | ------------------------------------ |
| `this`       | Android context for your application |
| `appID`      | CometChat App ID                     |
| `appSetting` | An object of the AppSettings class.  |

### AppSettings Options

| Method                                | Description                                          | Default  |
| ------------------------------------- | ---------------------------------------------------- | -------- |
| `setRegion(region)`                   | Region where your app was created (`us`, `eu`, `in`) | Required |
| `subscribePresenceForAllUsers()`      | Subscribe to presence events for all users           | —        |
| `subscribePresenceForRoles(roles)`    | Subscribe to presence for specific roles             | —        |
| `subscribePresenceForFriends()`       | Subscribe to presence for friends only               | —        |
| `autoEstablishSocketConnection(bool)` | Let SDK manage WebSocket connections automatically   | `true`   |
| `overrideAdminHost(adminHost)`        | Custom admin URL (dedicated deployment)              | —        |
| `overrideClientHost(clientHost)`      | Custom client URL (dedicated deployment)             | —        |

### Auto Mode Connection

<Note>
  Know more about auto mode connection [click here](/sdk/android/connection-behaviour#auto-mode)
</Note>

| App State         | Behaviour                               |
| ----------------- | --------------------------------------- |
| App in foreground | Connected with WebSocket                |
| App in background | Immediately disconnected with WebSocket |

### Manual Mode Connection

<Note>
  Know more about manual mode connection [click here](/sdk/android/connection-behaviour#manual-mode)
</Note>

| App State         | Behaviour                                                                                                          |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| App in foreground | Call `CometChat.connect()` to create the WebSocket connection                                                      |
| App in background | Disconnect the WebSocket connection if no ping is received within 30 seconds after the app goes in the background. |

<Warning>
  **Auth Key** is for development/testing only. In production, generate **Auth Tokens** on your server using the REST API and pass them to the client. Never expose Auth Keys in production client code.
</Warning>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/sdk/android/authentication-overview">
    Learn about secure authentication with Auth Tokens for production apps
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/sdk/android/send-message">
    Start sending text, media, and custom messages to users and groups
  </Card>

  <Card title="Key Concepts" icon="book" href="/sdk/android/key-concepts">
    Understand core concepts like users, groups, messages, and conversations
  </Card>

  <Card title="User Management" icon="user" href="/sdk/android/user-management">
    Create and manage users in your CometChat application
  </Card>
</CardGroup>