Setup

Install and initialize the CometChat Android SDK in your application

Quick Setup Reference

// 1. Add dependency to build.gradle
implementation "com.cometchat:chat-sdk-android:4.1.8"

// 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 → Your App → API & Auth Keys

Skip the create new app step. Your existing v2 app can be migrated to v3. Follow the steps mentioned in the Add the CometChat dependency section below to upgrade to the latest version of v3.

Get your Application Keys

Sign up for CometChat and then:

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

Minimum Requirements

• Android API Level 21
• Android API Level 24 (if you are using the Calls SDK)
• AndroidX Compatibility

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:

Groovy

allprojects {
  repositories {
    maven {
      url "https://dl.cloudsmith.io/public/cometchat/cometchat/maven/"
    }
  }
}

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

Groovy

dependencies {
  implementation "com.cometchat:chat-sdk-android:4.1.8"
}

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.

Finally, add the following lines to the android section of the app level gradle file.

Groovy

android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

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

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

Java

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());
  }
});

Kotlin

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)
    }
  }
)

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

Auto Mode Connection

Know more about auto mode connection click here

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

Manual Mode Connection

Know more about manual mode connection click here

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.

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.

---

Next Steps

Authentication

Learn about secure authentication with Auth Tokens for production apps

Send Messages

Start sending text, media, and custom messages to users and groups

Key Concepts

Understand core concepts like users, groups, messages, and conversations

User Management

Create and manage users in your CometChat application