An installation guide for the Kustomer Chat Android SDK.

This guide covers how to install the Chat Android SDK. For a quick start guide, see Quick start: Chat SDK for Android.


See Requirements.


OkHttp library version

This SDK uses the OkHTTP library version 3.14.9 and resolves the dependency automatically. This SDK might not work correctly if you explicitly use an okHTTP library version of 4.X.X in your project.

Install the Kustomer Chat Android SDK

The Kustomer Chat UI and Core libraries are hosted on the Maven Central Repository.


What happened to the Android Kustomer Chat SDKs hosted on Bintray and JCenter?

If you've implemented a version our Android SDK hosted on Bintray or JCenter, see our announcement in the changelog for Android Chat SDK v2.5.0.

You can install the Chat Android SDK files with either Gradle or Maven.

Install with Gradle

Add the following dependency to your app-level build.gradle:

dependencies {
      implementation '<<Android_SDK_Version>>'
      // Other dependencies.

Make sure the Maven Central repository is included in your root-level build.gradle:

allprojects {
    repositories {

Install with Maven

Maven: Add the Kustomer UI dependency:


Initialize the Chat Android SDK

Use Kustomer.init() to initialize Kustomer Chat from your Application class:



To use the code sample for your app, replace api key with an API key with the org.tracking role for your Kustomer organization.

//Init will throw AssertionException if the API Key used is invalid
Kustomer.init(application = this, apiKey = apiKey) { result: KusResult<Boolean> ->
            Log.i(TAG,"Kustomer is initialized ${result.dataOrNull}")


Always initialize with an Application class

You must always have an Application class to initialize Kustomer Chat properly. Create an Application class before you call Kustomer.init().

Initialize Chat Android SDK with options

You can also use KustomerOptions.Builder() and pass the options object during Kustomer.init() to initialize the Chat Android SDK with options to override any settings in the SDK. For more information, see the 'KustomerOptions` class reference.

We've include a code sample below.



To use the code sample for your app, replace "api key" with an API key with the org.tracking role for your Kustomer organization.

//KustomerOptions is optional. Only use options to override any settings directly in the SDK

val options = KustomerOptions.Builder()  
            .setKnowledgeBaseId("CUSTOM_KB_ID") // Deprecated
            .hideNewConversationButton(true | false)
            .hideHistoryNavigation(true | false)
//Init will throw AssertionException if the API Key used is invalid
Kustomer.init(application = this, apiKey = apiKey, options = {
            Log.i(TAG,"Kustomer is initialized ${it.dataOrNull}")


Guide: Build your own UI πŸ“™

Visit Build your own UI to learn how to build your own mobile Chat UI with the Kustomer Core SDK.


Guide: Localization πŸ“™

Visit Localization to learn how to change and override the default language settings.

KustomerOptions class reference

chatAssistantIdStringOverrides the chat assistant id
businessScheduleIdStringOverrides the business schedule id

Deprecated for Chat 2.0
StringOverrides the Knowledge Base id.

This method has been deprecated. Use brandId instead to fetch brand-specific chat settings, including a brand-specific Knowledge Base.
brandIdStringProvides a Brand ID to fetch brand-specific chat settings
userLocaleLocaleOverrides the device locale
hideNewConversationButtonBool. Default is false.Hides "New Conversation" button if set to true.
logLevelKusLogOptionsEnables logs for the SDK
hideHistoryNavigationBool. Default is false.Hides the back button on Conversation view
hideKbArticleShareBool. Default is false.Hides the share option from UI when viewing Knowledgebase Articles view
showInAppNotificationsBool. Default is true.Determines if in-app notifications should be shown.

To learn how to configure Kustomer Chat further with the Android SDK, see Overview: Android SDK.

Override SDK library dependencies with Gradle

If your app has a dependency conflict from different library versions, you can override the library version used in the Kustomer Chat Android SDK.

To override SDK library dependencies, declare the associated Kus version variable in build.gradle for your app:

ext.kus_kotlin_version = "YOUR_KOTLIN_VERSION"
ext.kus_firebase_version = "YOUR_FIREBASE_MESSAGING_VERSION"


Always check the Kustomer SDK after a version update or override

SDK library dependency overrides can contain changes that can break the API and cause issues. Always make sure that the Kustomer Chat SDK is working properly after a version update or any overrides.

Chat Android SDK dependencies

The Kustomer Chat Android SDK uses the following dependencies with their version variables:

    kus_kotlin_version = "1.4.21"
    kus_kotlin_coroutines_version = "1.3.4"

    kus_retrofit_version = "2.9.0"

    kus_moshi_version = "1.11.0"

    // Firebase
    kus_firebase_version = "20.2.4"

    // App dependencies
    kus_pubnub_version = "5.1.1"
    kus_material_version = "1.2.0"
    kus_glide_version = "4.11.0"
    kus_swiperefreshlayout_version = "1.1.0"
    kus_markwon_version = "4.6.0"
    kus_exif_interface_version = "1.3.2"

    // Architecture Components
    kus_lifecycle_extensions_version = "2.2.0"
    kus_navigation_fragment_version = "2.3.0"
    kus_navigation_ui_version = "2.3.0"
    kus_constraintlayout_version = "2.0.0-beta7"
    kus_appcompat_version = "1.2.0"
    kus_navigation_safe_args_version = "1.0.0"
    kus_webkit_version = "1.3.0"

    // Kotlin
    api "org.jetbrains.kotlin:kotlin-stdlib:$kus_kotlin_version"
    api "org.jetbrains.kotlinx:kotlinx-coroutines-core:$kus_kotlin_coroutines_version"
    api "org.jetbrains.kotlinx:kotlinx-coroutines-android:$kus_kotlin_coroutines_version"

    implementation "com.squareup.retrofit2:retrofit: $kus_retrofit_version"
    implementation "com.squareup.retrofit2:converter-moshi:$kus_retrofit_version"

    api "com.squareup.moshi:moshi:$kus_moshi_version"
    kapt "com.squareup.moshi:moshi-kotlin-codegen:$kus_moshi_version"
    implementation "com.squareup.moshi:moshi-adapters:$kus_moshi_version"

    // Firebase
    implementation "$kus_firebase_version"

    // App dependencies
    implementation group: 'com.pubnub', name: 'pubnub-kotlin', version: kus_pubnub_version
    implementation "$kus_material_version"
    implementation "com.github.bumptech.glide:glide:$kus_glide_version"
    implementation "androidx.swiperefreshlayout:swiperefreshlayout:$kus_swiperefreshlayout_version"
    implementation "io.noties.markwon:core:$kus_markwon_version"

    // Architecture components
    implementation "androidx.lifecycle:lifecycle-extensions:$kus_lifecycle_extensions_version"
    implementation "androidx.lifecycle:lifecycle-viewmodel-ktx:$kus_lifecycle_extensions_version"
    implementation "androidx.lifecycle:lifecycle-livedata-ktx:$kus_lifecycle_extensions_version"
    implementation "androidx.navigation:navigation-fragment-ktx:$kus_navigation_fragment_version"
    implementation "androidx.navigation:navigation-ui-ktx:$kus_navigation_ui_version"
    implementation "androidx.constraintlayout:constraintlayout:$kus_constraintlayout_version"
    implementation "androidx.appcompat:appcompat:$kus_appcompat_version"
    implementation "androidx.webkit:webkit:$kus_webkit_version"
    implementation 'androidx.legacy:legacy-support-v4:1.0.0'
    classpath "android.arch.navigation:navigation-safe-args-gradle-plugin:$kus_navigation_safe_args_version"
    implementation "androidx.exifinterface:exifinterface:$kus_exif_interface_version"

What’s Next