Installation

Overview

Kommunicate is live chat and chatbots powered customer support software. Kommunicate allows you to add customizable live chat SDK to your Android apps. It enables you to chat with your app users and customers through a customizable chat interface.

Installing Kommunicate in your Android app is easy and fast. We will walk you through the procedure so you can start answering your support queries within a few minutes.

Add the following in your app's(app level) build.gradle dependency:

dependencies {
//...
implementation 'io.kommunicate:kommunicate:1.9.0'
}

NOTE: Kommunicate requires minimum Android SDK 16 or higher. Be sure to check if that is what you are using. You can find the minimum android SDK version in your app's build.gradle file, inside defaultConfig. The field is named as minSdkVersion.

Building with ProGuard

If you are using ProGuard in your application, then add the below rules to your proguard-rules.pro file:

#keep JSON classes                
-keepclassmembernames class * extends com.applozic.mobicommons.json.JsonMarker {
    !static !transient <fields>;
}

-keepclassmembernames class * extends com.applozic.mobicommons.json.JsonParcelableMarker {
    !static !transient <fields>;
}

#GSON Config          
-keepattributes Signature          
-keep class sun.misc.Unsafe { *; }           
-keep class com.google.gson.examples.android.model.** { *; }            
-keep class org.eclipse.paho.client.mqttv3.logging.JSR47Logger { *; } 
-keep class android.support.** { *; }
-keep interface android.support.** { *; }
-dontwarn android.support.v4.**
-keep public class com.google.android.gms.* { public *; }
-dontwarn com.google.android.gms.**
-keep class com.google.gson.** { *; }

Get your APP_ID

Sign up for Kommunicate to get your APP_ID. You will get the APP_ID from the Install section. This APP_ID is used to create/launch conversations.

Initialize SDK

After the Gradle sync is finished with Kommunicate dependency, you can initialize the SDK by calling the below method:

 Kommunicate.init(context, APP_ID);

You can initialize the SDK in onCreate() function of your Activity. Just make sure it is initialized before accessing any method from the Kommuniate SDK. The APP_ID parameter will take the application id(APP_ID) you just acquired.

For the context parameter you can pass the application context using the getApplicationContext() method. However if you are unable to get that, you can also pass the activity context.

Launch conversation

Kommunicate provides KmConversationBuilder class to create and launch conversation directly. This way, you can save the extra steps of authentication, creation, initialization and launch.

Launch conversation for visitors:

If you would like to launch the conversation directly without making the user entering any details, then use the builder as below:

       new KmConversationBuilder(activityContext).launchConversation(new KmCallback() {
                        @Override
                        public void onSuccess(Object message) {
                            Log.d("Conversation", "Success : " + message);
                        }

                        @Override
                        public void onFailure(Object error) {
                            Log.d("Conversation", "Failure : " + error);
                        }
                    });

For the activityContext parameter you need to pass the activity context. One way to get it is the YourActivityName.this.

Launch conversation for visitors with pre-chat lead collection forms:

If you need the user to fill in details such as name, email and phone number before starting the conversation then launch the conversation with withPreChat flag as true. In this case, you wouldn't need to pass the kmUser details.

A screen would open up for the user asking for the details. Once the user fills the valid details (at least either email or phone number is required), the conversation would be launched. Use the builder as below:

     new KmConversationBuilder(activityContext).setWithPreChat(true).launchConversation(new KmCallback() {
                        @Override
                        public void onSuccess(Object message) {
                            Log.d("Conversation", "Success : " + message);
                        }

                        @Override
                        public void onFailure(Object error) {
                            Log.d("Conversation", "Failure : " + error);
                        }
                    });

For the activityContext parameter you need to pass the activity context. One way to get it is the YourActivityName.this.

Launch conversation with existing user:

If you already have the user details then create a KMUser object using the details and launch the conversation. Use the builder as below to create KMUser object with already existing details:

    KMUser user = new KMUser();
    user.setUserId(userId); // Pass a unique key
    user.setImageLink(image-url); // Optional

Then pass this user object to the setKmUser method as below:

new KmConversationBuilder(activityContext).setKmUser(user).launchConversation(new KmCallback() {
                        @Override
                        public void onSuccess(Object message) {
                            Log.d("Conversation", "Success : " + message);
                        }

                        @Override
                        public void onFailure(Object error) {
                            Log.d("Conversation", "Failure : " + error);
                        }
                    });

For the activityContext parameter you need to pass the activity context. One way to get it is the YourActivityName.this.

The KmConversationBuilder object (Launch a custom conversation):

You can customize the process of creating or launching a conversation by building the KmConversationBuilder object according to your requirements.

Here is the list of parameters along with the methods you can pass in KmConversationBuilder to customize the conversation according to your requirements:

Note: The parameters should be passed as arguments in the methods.

Parameter	Parameter type	Method	Description
context	Activity	new KmConversationBuilder(<context>)	Passed in the constructor. Only Activity Context is accepted. Exception is thrown otherwise
APP_ID	String	setAppId(<APP_ID>)	Ignore if you have already initialized the SDK with APP_ID
kmUser	KMUser	setKmUser(<kmUser>)	If you have user details, you can pass them here. Ignore if you do not have user details.
withPreChat	boolean	setWithPreChat(<withPreChat>)	Pass true if you would like the user to fill the details (such as name, email and phone etc.) before starting the chat. If you already have user details, then you can pass false.
isSingleConversation	boolean	setSingleConversation(<isSingleConversation>)	Pass false if you would like to create new conversation every time a particular user starts a conversation. This is true by default which means only one conversation will open for the user every time the user starts a conversation.
agentList	List<String>	setAgentIds(<agentList>)	Pass the list of human agents. The agent IDs would be the email IDs of your team members which they used to register on Kommunicate. Otherwise, you can ignore it if you want to assign the conversation to the default agent.
botList	List<String>	setBotIds(<botList>)	Pass the list of bots. In Kommunicate dashboard, go to the Bots section -> Integrated bots -> Copy botID. Otherwise ignore if you haven't integrated any bots
clientConversationId	String	setClientConversationId(<clientConversationId>)	Set the clientConversationId if you would like to identify a conversation based on your unique ID. One clientConversationId is mapped to only one conversation. Whenever this clientConversationId is passed to launch or create a conversation, the same conversation would be opened.
fcmDeviceToken	String	setFcmDeviceToken(<fcmDeviceToken>)	Pass the fcmDeviceToken (Push notification token from FCM) obtained from FirebaseInstanceIdListener. Refer here for more details.
messageMetadata	Map<String, String>	setMessageMetadata(<messageMetadata>)	This metadata, if set, will be sent with all the messages sent from that device. Also, this metadata will be set to all the conversations created from that device.
conversationAssignee	String	setConversationAssignee(<conversationAssignee>)	Should be either an agent Id or a botId. If set, will assign the conversation to the agent or bot thus skipping the routing rules set in the dashboard.
conversationMetadata	Map<String, String>	setConversationMetadata(<conversationMetadata>)	This metadata, if set, will be sent with the conversation.
callback	KmCallback	launchConversation(<callback>) OR createConversation(<callback>)	Callback to notify Success or Failure

The difference between launchConversation and createConversation is that launchConversation will launch the chat after creating it, whereas createConversation will only create the chat and won't launch it, returning the conversationId. To launch this created conversation in future use this method.

Below are some examples of how you can customize the builder for launching a single conversation thread. If you want to create a new conversation every time then call .setSingleConversation(false) on the builder. Note that, if you are doing so, the conversation history will not be retained.

If you have a different use-case and would like to customize the conversation creation, user creation and conversation launch, you can explore our docs further.