Introduction: Kustomer Android SDK - Support your customers in your Android app.
More: Author   ReportBugs   

The Android SDK for the mobile client


v0.2.0+: identify() & isChatAvailable() methods will always return callback on background thread. See changelog


  • A API Key
  • Android Min SDK Version 19 i.e.., Android 4.4 Kitkat


The Kustomer Android SDK requires a valid API Key with role org.tracking. See Getting Started - Create an API Key



Include the library in your app.gradle:

implementation 'com.kustomer.kustomersdk:kustomersdk:0.2.0'

Or through Maven



  1. In your project's Application Class: ```java import com.kustomer.kustomersdk.Kustomer;

private static final String K_KUSTOMER_API_KEY = "YOUR_API_KEY";

@Override public void onCreate() { super.onCreate(); Kustomer.init(this, K_KUSTOMER_API_KEY); }

2. When you want to present the Kustomer chat interface to your users:

Intent intent = new Intent(activity, KUSSessionsActivity.class);

// OR

Add permissions to manifest:
  1. Internet Permissions (Required):

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  2. Multimedia Permissions (Optional):

    <uses-permission android:name="android.permission.CAMERA"/>
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

Note: If neither of the Multimedia Permissions is declared, the image attachments button will be hidden.

Declaring Activities
  1. Add KUSSessionsActivity & KUSChatActivity into your AndroidManifest.xml ```xml

### Additional API Reference

// Initialize the Kustomer android SDK with an API key, and start a user session.
Kustomer.init(this, "API_KEY");
// Convenience method that will present the chat interface.

// Convenience methods that will present a browser interface pointing to your KnowledgeBase.

// Convenience method that will present a custom web page interface
// Resets the user session, clearing the user's access to any existing chats from the device.
// Securely identify a customer. Requires a valid JSON Web Token.
Kustomer.identify("SECURE_ID_HASH", new KUSIdentifyListener() {
  public void onComplete(final boolean success) {
      // Note: This will be called on background thread

 Identifying users is the best way to ensure your users have a great chat experience because
 it gives them access to all of the previous conversations across devices.
 By default, users can see their conversation history only on a single device. By including a secure
 hash with the ID of your user, you can securely identify that user and grant them access.

 JSON Web Token:
 The JWT used for secure identification must use HMAC SHA256 and include the following header and claims:
 Header: { "alg" : "HS256", "typ" : "JWT" }
 Claims: { "externalId" : "your_user_id", "iat" : "current_time_utc" }
 NOTE: tokens with an @"iat" older than 15 minutes will be rejected

 The JWT must be signed with your organization's secret. This secret is accessible to your server,
 via `/v1/auth/customer/settings`. The intent is that your own server fetches the secret, generates
 and signs the JWT and then sends it to your client which in turn calls the `+[Kustomer identify:]`
 method, preventing any risk of falsified indentification calls.
 Attach custom attributes to the user

 Attached key-value pairs via the `custom` property must be enabled on the Customer Klass via the admin portal.
 This can be done by an admin via Settings > Platform Settings > Klasses > Customer

KUSCustomerDescription customerDescription = new KUSCustomerDescription();

JSONObject customObject = new JSONObject();
customObject.put("customAttributeStr", "value");
// ...


 Attach custom attributes to the user's most recent conversation (or the first one they create)

 These key-value pairs must be enabled on the Conversation Klass via the admin portal.
 This can be done by an admin via Settings > Platform Settings > Klasses > Conversation

JSONObject conversationObject = new JSONObject();
conversationObject.put("customAttributeStr", "value");
// ...


 Attach custom attributes to the user's next new conversation

 These key-value pairs must be enabled on the Conversation Klass via the admin portal.
 This can be done by an admin via Settings > Platform Settings > Klasses > Conversation
JSONObject conversationObject = new JSONObject();
conversationObject.put("customAttributeStr", "value");
// ...

 Mark the user as having navigated to a new page. By marking the user's progress around the app, you will be able to create proactive conversational campaigns that can be triggered as a result of the user's progress in your application flow.
    protected void onCreate(Bundle savedInstanceState) {

    // Track the current page on appearance

 You should also declare the following receiver in manifest file to allow proactive notifications to be dismissed.

Check chat management status asynchronously to enable support chat.
Kustomer.isChatAvailable(new KUSChatAvailableListener(){
    public void onSuccess(boolean enabled){
        // Note: This will be called on background thread

        // This is called when API call is successful.
        // enabled represent chat management settings.


    public void onFailure(){
        // Note: This will be called on background thread

        // This is called when API call fails.
 Show/Hide the "New Conversation" button in closed chat. By default, "Start New Conversation" button will appear in closed chat listing. You can update the settings by this method.
 Return the total number of open conversations.
 Return the current count of un-read messages. It might not be immediately available.
 Override the conversation form directly from the sdk by setting the form id. 


Theme Customization:

For theme customization, you should always extend theme for support activities from KUSAppTheme and pass it to activities in the manifest. Only include items that you want to customize.

<style name="MySupportTheme" parent="KUSAppTheme">
  <item name="colorPrimary">@color/kusToolbarBackgroundColor</item>
  <item name="colorPrimaryDark">@color/kusStatusBarColor</item>
  <item name="colorAccent">@color/kusColorAccent</item>
  <item name="kus_back_image">@drawable/ic_arrow_back_black_24dp</item>
  <item name="kus_dismiss_image">@drawable/ic_close_black_24dp</item>
  <item name="kus_new_session_button_image">@drawable/ic_edit_white_20dp</item>
Font Customization:

Import the font files in res/font & create a file i.e montserrat.xml

<?xml version="1.0" encoding="utf-8"?>
<font-family xmlns:android=""

  <font android:fontStyle="normal" 

  <font android:fontStyle="italic" 
        app:font="@font/montserrat_regular" />


For more detail: Please have a look at Fonts In XML

You can define any of the following in your res/values/style to customize font.

<style name="KUSChatMessageTimeStampTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>

<style name="KUSChatMessageTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>

<style name="KUSChatSessionTitleTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>
<style name="KUSChatSessionSubtitleTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>
<style name="KUSChatSessionDateTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>
<style name="KUSChatSessionUnreadTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>

<style name="KUSToolbarNameTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>
<style name="KUSToolbarGreetingTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>
<style name="KUSToolbarUnreadTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>

<style name="KUSNewSessionButtonAppearance" parent="@style/TextAppearance.AppCompat.Button">
    <item name="android:fontFamily">@font/montserrat</item>

<style name="KUSEmailInputPromptTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>
<style name="KUSEmailInputTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>

<style name="KUSInputBarTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>
<style name="KUSOptionPickerTextAppearance" parent="@style/TextAppearance.AppCompat">
    <item name="android:fontFamily">@font/montserrat</item>

Additional Customization

You can define any of the following items in their respective res files to change them.

Sessions Screen:
<color name="kusToolbarBackgroundColor">#000000</color>
<color name="kusStatusBarColor">#000000</color>
<color name="kusToolbarTintColor">#DD2C00</color>
<color name="kusSessionListBackground">#909090</color>
<color name="kusSessionItemBackground">#909090</color>
<color name="kusSessionItemSelectedBackground">#55FFFFFF</color>
<color name="kusSessionTitleColor">#FFFFFF</color>
<color name="kusSessionDateColor">#FFFFFF</color>
<color name="kusSessionSubtitleColor">#FFFFFF</color>
<color name="kusSessionUnreadColor">#FFFFFF</color>
<color name="kusSessionUnreadBackground">#3F51B5</color>
<color name="kusSessionPlaceholderBackground">#909090</color>
<color name="kusSessionPlaceholderLineColor">#55FFFFFF</color>
<color name="kusNewSessionButtonColor">#DD2C00</color>
<color name="kusNewSessionTextColor">#FFFFFF</color>

<string name="com_kustomer_new_conversation">New Conversation</string>

<bool name="kusNewSessionButtonHasShadow">true</bool>

Before and after:


Chat screen:
<color name="kusToolbarNameColor">#FFFFFF</color>
<color name="kusToolbarGreetingColor">#FFFFFF</color>
<color name="kusToolbarSeparatorColor">#BDBDBD</color>
<color name="kusToolbarUnreadTextColor">#FFFFFF</color>
<color name="kusToolbarUnreadBackground">#aacc0000</color>
<color name="kusEmailInputBackground">#FFFFFF</color>
<color name="kusEmailInputBorderColor">#DD2C00</color>
<color name="kusEmailInputPromptColor">#FFFFFF</color>
<color name="kusChatListBackground">#909090</color>
<color name="kusChatItemBackground">#909090</color>
<color name="kusChatTimestampTextColor">#FFFFFF</color>
<color name="kusCompanyBubbleColor">#000000</color>
<color name="kusCompanyTextColor">#FFFFFF</color>
<color name="kusUserBubbleColor">#DD2C00</color>
<color name="kusUserTextColor">#000000</color>
<color name="kusSendButtonColor">#DD2C00</color>
<color name="kusInputBarTintColor">#DD2C00</color>
<color name="kusInputBarHintColor">#EEEEEE</color>
<color name="kusInputBarTextColor">#FFFFFF</color>
<color name="kusInputBarBackground">#000000</color>
<color name="kusInputBarSeparatorColor">#BDBDBD</color>
<color name="kusInputBarAttachmentIconColor">#FFFFFF</color>
<color name="kusOptionPickerSeparatorColor">#BDBDBD</color>
<color name="kusOptionPickerButtonBorderColor">#2962FF</color>
<color name="kusOptionPickerButtonTextColor">#2962FF</color>
<color name="kusOptionPickerButtonBackground">#F5F5F5</color>

<string name="com_kustomer_type_a_message">Type a message...</string>
<string name="com_kustomer_dont_miss_a_response_get_notified_soon_by_email">Don\'t miss a response! Get notified by email:</string>
<string name="com_kustomer_email_example"></string>

<integer name="kusMaximumAvatarsToDisplay">3</integer>

Before and after:



Kustomer SDK support both Right-to-left (RTL) and Left-to-right (LTR) formatted languages. English and Urdu language translation is already added in SDK.

// List of all strings that you can override
 <string name="com_kustomer_week">week</string>
     <string name="com_kustomer_day">day</string>
     <string name="com_kustomer_hour">hour</string>
     <string name="com_kustomer_minute">minute</string>
     <string name="com_kustomer_weeks">weeks</string>
     <string name="com_kustomer_days">days</string>
     <string name="com_kustomer_hours">hours</string>
     <string name="com_kustomer_minutes">minutes</string>
     <string name="com_kustomer_just_now">Just now</string>
     <string name="com_kustomer_ago">ago</string>

     <string name="com_kustomer_attachment">Attachment</string>
     <string name="com_kustomer_camera">Camera</string>
     <string name="com_kustomer_gallery">Gallery</string>
     <string name="com_kustomer_cancel">Cancel</string>

     <string name="com_kustomer_something_went_wrong_please_try_again">Something went wrong. Please try again.</string>
     <string name="com_kustomer_try_again">Try Again</string>
     <string name="com_kustomer_new_conversation">New Conversation</string>
     <string name="com_kustomer_dont_miss_a_response_get_notified_soon_by_email">Don\'t miss a response! Get notified by email:</string>
     <string name="com_kustomer_email_example"></string>
     <string name="com_kustomer_type_a_message...">Type a message…</string>
     <string name="com_kustomer_Loading...">Loading…</string>

     <string name="com_kustomer_chat_with">Chat with</string>
     <string name="com_kustomer_processing">Processing…</string>
     <string name="com_kustomer_no_internet_connection">No Internet Connection</string>
     <string name="com_kustomer_chat_screen">Chat Screen</string>
     <string name="com_kustomer_we_re_here_let_us_know_if_we_can_help">We\'re here, Let us know if we can help.</string>

     <string name="com_kustomer_example">Example</string>
     <string name="com_kustomer_please_provide_a_message_body">Please provide a message body</string>
     <string name="com_kustomer_no_internet_message">The Internet connection appears to be offline.</string>
     <string name="com_kustomer_camera_permission_denied">Camera permission is denied.</string>
     <string name="com_kustomer_storage_permission_denied">Storage permission is denied.</string>
     <string name="com_kustomer_authorities">authority</string>
     <string name="com_kustomer_share_via">Share Via</string>
     <string name="com_kustomer_please_provide_storage_permission">Please provide storage permission to this app</string>
     <string name="com_kustomer_dismiss">Dismiss</string>
     <string name="com_kustomer_closed">CLOSED</string>
     <string name="com_kustomer_start_a_new_conversation">Start a New Conversation</string>
     <string name="com_kustomer_thank_you_we_will_follow_up_on_your_request">Thank You! We\'ll follow up on your request.</string>
     <string name="com_kustomer_chat_has_ended">CHAT HAS ENDED</string>
     <string name="com_kustomer_end_chat">END CHAT</string>
     <string name="com_kustomer_back_to_chat">Back to Chat</string>
     <string name="com_kustomer_leave_a_message">Leave a message</string>

Customize existing strings

If you are interested in adding translation for SDK specified language but with different translation then you just need to add the strings file for the respective language in your app and write any of the strings defined above and change the translation.

Add new localization

If the SDK does not include localized strings for the language you are interested in, you can add new ones. You just need to add the strings file for the respective language in your app and write all of the strings defined above and add the translation for that language.

Custom locale

By default, SDK use mobile preferred locale. If you want to use different locale, you can override locale as well. To do that:

// Set Custom Locale
Kustomer.setLocale(new Locale("language_code"));

// Example
Kustomer.setLocale(new Locale("ur"));

You must set locale before calling Kustomer.init() method. SDK will load only the language whose translation exists either in SDK or in project. If specified language's translation doesn't exist, SDK will try to load translation of mobile preferred languages before using default language.

After setting SDK locale, SDK automatically updates the layout (LTR or RTL) and will update the text for that language as well.


Incrementing the build version

  • Update the version number references in the above Installation section
  • Update the libraryVersion in the SDK's build.gradle file (/kustomersdk/build.gradle)
  • Update the changelog if necessary
  • Run the following command on the root of the project. ./gradlew install bintrayUpload. Make sure you have the correct bintray.user & bintray.apikey values in file.
  • Commit & push the changes
Support Me
About Me
Google+: Trinea trinea
GitHub: Trinea