Platform
APIs & SDKs
Resources
Go to Console

LiveChat for Android

An Android SDK for integrating LiveChat functionality into your mobile application.

Getting started

Add real-time customer support to your Android application with LiveChat's native SDK. This guide covers installation, basic setup, and advanced features.

💡 The SDK is now Kotlin-based and uses the new package com.livechatinc.chatsdk. See migration notes if you are upgrading from v2.x.x.

Requirements

The Android SDK is compatible with:

  • Android 5.0 (API level 21) or higher
  • Java 8 or higher

Installation

To install the SDK, first add the JitPack repository to your root build.gradle:

ADD JITPACK REPOSITORY
Copied!
allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

Next, add dependency to your app's build.gradle:

ADD DEPENDENCY
Copied!
dependencies {
    implementation 'com.github.livechat:chat-window-android:3.0.0'
}

Then, add Internet permission to AndroidManifest.xml:

ADD PERMISSION
Copied!
<uses-permission android:name="android.permission.INTERNET" />

Initialization

You can initialize the SDK in the onCreate() method of your Application instance:

INITIALIZE
Copied!
LiveChat.initialize("<LICENSE>", this)

Display the chat window

The function below allows you to display a chat to a customer:

SHOW CHAT
Copied!
LiveChat.getInstance().show()

That's it! Your customers can start chatting with you now.

Customer information

You can pre-fill the pre-chat form fields with customer information to provide your agents with more details about the customer. All information is optional.

The group ID defaults to 0 if not provided.

CUSTOMER INFO - KOTLIN
Copied!
LiveChat.getInstance().setCustomerInfo(
    "Joe", // Name
    "joe@mail.com", // Email
    "0", // Group ID, defaults to "0"
    Collections.singletonMap("internalCustomerId", "ABC123") // Custom params
)
CUSTOMER INFO - JAVA
Copied!
Map<String, String> customParams = new HashMap<>();
customParams.put("internalCustomerId", "ABC123");
LiveChat.getInstance().setCustomerInfo(
    "Joe", // Name
    "joe@mail.com", // Email
    "0", // Group ID
    customParams // Custom params
);

Note: You should call the setCustomerInfo() before LiveChat.getInstance().show(). To update customer properties when the chat has already loaded, recreate it with LiveChat.getInstance().destroyLiveChatView() and LiveChat.getInstance().getLiveChatView().

Unread message counter

To get notified about new messages in the chat, use com.livechatinc.chatsdk.src.domain.listeners.NewMessageListener.

Set it wherever you want to react to a new message, for example, to increase the badge count.

NEW MESSAGES - KOTLIN
Copied!
LiveChat.getInstance().newMessageListener =
    NewMessageListener { message, isChatShown ->
        // Handle new message
    }
NEW MESSAGES - JAVA
Copied!
LiveChat.getInstance().setNewMessageListener((chatMessage, isChatShown) -> {
    // Handle new message
});

UI customization

While the chat appearance and language are managed through the application settings, you can customize the error view when the chat cannot be loaded.

Error view

You can localize and change the text displayed in the error view by overriding string resources in your app's strings.xml. All strings can be found in the GitHub repository.

You can also entirely override the default error view by including live_chat_error_layout.xml in your app's layout resources.

Note: Your custom error view must contain a View with live_chat_error_button id when using LiveChat.getInstance().show().

Activity

By default, activity will follow your activity's theme. To change this configuration, you can override the activity declaration in your app's AndroidManifest.xml file.

Clearing chat session

The chat window uses WebView's cookies to store the session. To clear the chat session, call:

CLEAR CHAT SESSION
Copied!
LiveChat.getInstance().signOutCustomer()

Link handling

By default, links in the chat are opened in the customer's default browser. If you want to intercept the link and handle it in your app, provide your UrlHandler.

HANDLE LINKS - KOTLIN
Copied!
LiveChat.getInstance().urlHandler =
        UrlHandler { url ->
            // Return true if handled, false to open in browser
            return@UrlHandler false
        }
HANDLE LINKS - JAVA
Copied!
LiveChat.getInstance().setUrlHandler(uri -> {
    // Return true if handled, false to open in browser
    return false;
});

Troubleshooting

Error handling

You can set an error listener to monitor and handle issues related to loading the chat view. This allows you to capture and respond to errors in a centralized way. Common use cases include reporting errors to analytics platforms or implementing custom error-handling logic.

ERRORS - KOTLIN
Copied!
LiveChat.getInstance().errorListener = ErrorListener { error ->
    // Handle the error
}
ERRORS - JAVA
Copied!
LiveChat.getInstance().setErrorListener((error) -> {});

Logger

You can configure the logging level to help with debugging and troubleshooting. Set the desired level before initializing LiveChat:

LOGGER - KOTLIN
Copied!
Logger.setLogLevel(Logger.LogLevel.VERBOSE)
LOGGER - JAVA
Copied!
Logger.setLogLevel(Logger.LogLevel.VERBOSE);

Refer to the Logger for all available log levels.

Note: Network calls require at least the INFO level. DEBUG and VERBOSE levels are more detailed.

Missing file picker activity

If you want to react or track instances where the activity for file picking on the user device is not found, you can set a listener for this event:

FILE PICKER NOT FOUND - KOTLIN
Copied!
LiveChat.getInstance().filePickerNotFoundListener = FilePickerActivityNotFoundListener {
    // Handle file picker activity not found
}
FILE PICKER NOT FOUND - JAVA
Copied!
LiveChat.getInstance().setFilePickerNotFoundListener(() -> {});

Advanced usage

The following features give you more control over the SDK integration. Note that they require additional implementation steps. If you decide to use any of these, please let us know about your use case — we would love to hear about it!

LiveChatView lifecycle scope

By default, after the LiveChat.getInstance().show() view is initialized, it's kept in the application memory. This allows you to react to new messages, for example, display a counter for unread messages. To automatically free up memory when the chat is no longer visible, you can use LiveChatViewLifecycleScope to control its lifecycle.

You should specify the scope when initializing the SDK:

LIFECYCLE SCOPE - KOTLIN
Copied!
LiveChat.initialize("<LICENSE>", this, lifecycleScope = LiveChatViewLifecycleScope.ACTIVITY)
LIFECYCLE SCOPE - JAVA
Copied!
LiveChat.initialize("<LICENSE>", this, LiveChatViewLifecycleScope.ACTIVITY);

Note: With the ACTIVITY scope, the NewMessageListener only works while the chat is visible.

Embed LiveChatView in your layout

You can embed the LiveChatView directly in your layout for more control over the chat window and its placement, instead of using LiveChat.getInstance().show(). For full implementation details, refer to the LiveChatActivity.

Here is a short overview of the steps to embed the LiveChatView in your layout:

1. Add LiveChatView to your layout

Begin with adding <com.livechatinc.chatsdk.src.presentation.LiveChatView /> to your layout XML file.

2. Provide activity or fragment context

During onCreate of your Activity or Fragment, call:

ATTACH CONTEXT
Copied!
liveChatView.attachTo(this)

This is required to properly handle the view's lifecycle, support file sharing, and launch links in the default external browser.

3. React to visibility events

Provide LiveChatView.InitListener when initializing the view:

VIEW INIT CALLBACK
Copied!
liveChatView.init(initCallbackListener)

Migrating from v2.5.0 to 3.0.0

If you're migrating from older SDK versions, here's the breakdown of the most important information you need to take note of:

  • The SDK is now Kotlin-based.
  • The API is now streamlined and uses the LiveChat singleton.
  • The package changed to com.livechatinc.chatsdk.

For the full migration guide, refer to the README available in the SDK's repository.

...

Join the community
Get in direct contact with us through Discord.
Follow us
Follow our insightful tweets and interact with our content.
Contribute
See something that's wrong or unclear? Submit a pull request.
Contact us
Want to share feedback? Reach us at: developers@text.com