Conversation
Overview
This section is dedicated to launching and managing chat conversations. You can set up how the list of conversations and new conversations are created and launched.
You can also create a conversation with specific human agents and bots. Also, you can either choose to open the same conversation thread for a particular user every time they come to chat or create a new thread instead.
Note: All the methods in this section accept
activityContext
since the process invloves launching an Activity. If you are calling the methods in Activity, then useYourActivity.this
in place ofactivityContext
. If you are calling the methods in Fragment, then usegetActivity()
in place ofactivityContext
.
Conversation
Open Conversation List
Open the conversation list screen (where all the conversations are listed in descending order of time of communication) by using the below method:
Kommunicate.openConversation(activityContext);
If you need a callback when the screen is opened, then use the below method:
Kotlin
If you are using kotlin:
Kommunicate.openConversation(activityContext, null, object : KmCallback {
override fun onSuccess(message: Any) {
Utils.printLog(activityContext, "ChatTest", "Launch Success : $message")
}
override fun onFailure(error: Any) {
Utils.printLog(activityContext, "ChatTest", "Launch Failure : $error")
}
})
Java
If you are using Java:
Kommunicate.openConversation(activityContext, null, new KmCallback() {
@Override
public void onSuccess(Object message) {
Utils.printLog(activityContext, "ChatTest", "Launch Success : " + message);
}
@Override
public void onFailure(Object error) {
Utils.printLog(activityContext, "ChatTest", "Launch Failure : " + error);
}
});
Open Particular Conversation
You can open a particular conversation if you have the conversationId of that particular conversation by using the below method:
Kotlin
If you are using Kotlin:
KmConversationHelper.openConversation(activityContext, true, conversationId, object : KmCallback {
override fun onSuccess(message: Any) {
// Implementation here
}
override fun onFailure(error: Any) {
// Implementation here
}
})
Java
If you are using Java:
KmConversationHelper.openConversation(activityContext, true, conversationId, new KmCallback() {
@Override
public void onSuccess(Object message) {
}
@Override
public void onFailure(Object error) {
}
});
The second parameter in the above method is skipConversationList
(passed as true
), pass it 'false' if you would like to show the conversation list after the user presses the back button in the conversation thread. If this parameter is passed 'true' then on pressing the back button, you would be navigated to the activity from where the conversation was launched, thus skipping the conversation list.
Create New Conversation
You can create a new conversation as below:
Kotlin
If you are using Kotlin:
KmConversationBuilder(activityContext)
.setSingleConversation(false) // Pass false if you would like to create new conversation every time 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.
.createConversation(object : KmCallback {
override fun onSuccess(message: Any) {
val conversationId = message.toString()
}
override fun onFailure(error: Any) {
Log.d("ConversationTest", "Error : $error")
}
})
Java
If you are using Java:
new KmConversationBuilder(activityContext)
.setSingleConversation(false) // Pass false if you would like to create new conversation every time 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.
.createConversation(new KmCallback() {
@Override
public void onSuccess(Object message) {
String conversationId = message.toString();
}
@Override
public void onFailure(Object error) {
Log.d("ConversationTest", "Error : " + error);
}
});
If you have the list of your human agents and/or bots and need to create a conversation with them then use the builder as described below:
Kotlin
If you are using Kotlin:
val agentIds = mutableListOf<String>()
agentIds.add("<AGENT_ID>") // Add AGENT_ID(s) to this list. The AGENT_ID is the email ID your human agent used to sign up on the Kommunicate dashboard.
val botIds = mutableListOf<String>()
botIds.add("<BOT_ID>") // Add BOT_ID(s) to this list. Go to Manage Bots(https://dashboard.kommunicate.io/bots/manage-bots) -> Copy botID
KmConversationBuilder(activityContext)
.setSingleConversation(false) // Pass false if you would like to create a new conversation every time the user starts a chat. This is true by default which means only one conversation will open for the user every time the user starts a chat.
.setAgentIds(agentIds) // The conversation will be created with these human agent(s)
.setBotIds(botIds) // The conversation will be created with these bot(s)
.setConversationAssignee("AGENT_ID/BOT_ID") // 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.
.createConversation(object : KmCallback {
override fun onSuccess(message: Any) {
val conversationId = message.toString()
}
override fun onFailure(error: Any) {
Log.d("ConversationTest", "Error : $error")
}
})
Java
If you are using Java:
List<String> agentIds = new ArrayList<>();
agentIds.add("<AGENT_ID>"); // Add AGENT_ID(s) to this list. The AGENT_ID is the email ID your human agent used to singup on Kommunicate dashboard.
List<String> botIds = new ArrayList<>();
botIds.add("<BOT_ID>"); // Add BOT_ID(s) to this list. Go to Manage Bots(https://dashboard.kommunicate.io/bots/manage-bots) -> Copy botID
new KmConversationBuilder(activityContext)
.setSingleConversation(false) // Pass false if you would like to create new conversation every time user starts a chat. This is true by default which means only one conversation will open for the user every time the user starts a chat.
.setAgentIds(agentIds) // The conversation will be created with these human agent(s)
.setBotIds(botIds) // The conversation will be created with these bot(s)
.setConversationAssignee("AGENT_ID/BOT_ID") //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.
.createConversation(new KmCallback() {
@Override
public void onSuccess(Object message) {
String conversationId = message.toString();
}
@Override
public void onFailure(Object error) {
Log.d("ConversationTest", "Error : " + error);
}
});
Single Conversation
You can create a unique conversation every time a particular user comes to chat by employing the below method.
A unique conversation is identified by the list of AGENT_IDs and BOT_IDs used to create the conversation. If the same set of IDs are passed to the below method, then the already existing conversation would be returned instead of creating a new conversation. A single unique conversation would be created if you skip the setSingleConversation
parameter in the builder.
Kotlin
If you are using Kotlin:
KmConversationBuilder(activityContext)
.createConversation(object : KmCallback {
override fun onSuccess(message: Any) {
val conversationId = message.toString()
}
override fun onFailure(error: Any) {
Log.d("ConversationTest", "Error : $error")
}
})
Java
If you are using Java:
new KmConversationBuilder(activityContext)
.createConversation(new KmCallback() {
@Override
public void onSuccess(Object message) {
String conversationId = message.toString();
}
@Override
public void onFailure(Object error) {
Log.d("ConversationTest", "Error : " + error);
}
});
If you have the list of your human agents and/or bots and need to create a single unique conversation with them then use the builder as described below:
Kotlin
If you are using Kotlin:
val agentIds = mutableListOf<String>()
agentIds.add("<AGENT_ID>") // Add AGENT_ID(s) to this list.
val botIds = mutableListOf<String>()
botIds.add("BOT_ID") // Add BOT_ID(s) to this list.
KmConversationBuilder(activityContext)
.setAgentIds(agentIds)
.setBotIds(botIds)
.createConversation(object : KmCallback {
override fun onSuccess(message: Any) {
// Implementation here
}
override fun onFailure(error: Any) {
// Implementation here
}
})
Java
If you are using Java:
List<String> agentIds = new ArrayList<>();
agentIds.add("<AGENT_ID>"); // Add AGENT_ID(s) to this list.
List<String> botIds = new ArrayList<>();
botIds.add("BOT_ID");// Add BOT_ID(s) to this list.
new KmConversationBuilder(activityContext)
.setAgentIds(agentIds)
.setBotIds(botIds)
.createConversation(new KmCallback() {
@Override
public void onSuccess(Object message) {
}
@Override
public void onFailure(Object error) {
}
});
Custom Title
In Kommunicate you can also create a conversation with a custom title. If you do this, then in place of the agent name, the title you give to the converation will be displayed on the toolbar.
Below are the steps to create a conversation with a custom title:
First create a
KmConverationBuilder
object using the code:new KmConversationBuilder(activityContext)
. Pass the activity context in context.Then set the conversation title on it using the
setConverationTitle("Your title")
method.Also call the
setSingleConversation(false)
method on the Converation Builder object. This will create a new conversation every time you create one.Then launch(or create) the conversation using the
launchConveration(KmCallback KmCallback)
method on the KmConverationBuilder object. This method take a KmCallback object. You will get the conversationId the message object on theonSuccess()
method callback of this object.You can use this
converationId
to later re-open the conversation, using this method.
You can refer to this code:
Kotlin
If you are using Kotlin:
KmConversationBuilder(activityContext)
.setConversationTitle("My Title")
.setSingleConversation(false)
.launchConversation(object : KmCallback {
override fun onSuccess(message: Any) {
// You can store this somewhere and later use it to re-open the conversation.
val conversationId = message.toString()
}
override fun onFailure(error: Any) {
// Implementation here
}
})
Java
If you are using java:
new KmConversationBuilder(activityContext)
.setConversationTitle("My Title")
.setSingleConversation(false)
.launchConversation(new KmCallback() {
@Override
public void onSuccess(Object message) {
//you can store this some where and later use to re-open the converation.
String conversationId = message.toString();
}
@Override
public void onFailure(Object error) {
}
});
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 |
---|---|---|---|
activityContext | Activity | new KmConversationBuilder(<activityContext>) | 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 Manage 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. |
String | setTeamId(<teamId>) | Set the team ID in the conversation builder to assign the conversation directly to a team. | |
conversationMetadata | Map<String, String> | setConversationMetadata(<conversationMetadata>) | This metadata, if set, will be sent with the conversation. |
callback | KmCallback | launchConversation(<callback>) OR createConversation(<callback> OR launchAndCreateIfEmpty(<callback>) | Callback to notify Success or Failure |
conversationInfo | Map<String, String> | .setConversationInfo(Map<String, String>) | properties displayed on dashboard specific to conversation |
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.
launchAndCreateIfEmpty
will create a conversation if it does not exist already and then launch it.
If you want to assign a conversation to a specific team based on location etc.., you can achieve it while creating the conversation. You need teamId for it and you can use the builder as described below:
Kotlin
If you are using Kotlin:
KmConversationBuilder(activityContext)
.setTeamId("team_id")
.createConversation(object : KmCallback {
override fun onSuccess(message: Any) {
// Implementation here
}
override fun onFailure(error: Any) {
// Implementation here
}
})
Java
If you are using Java:
new KmConversationBuilder(activityContext)
.setTeamId(“team_id”)
.createConversation(new KmCallback() {
@Override
public void onSuccess(Object message) {
}
@Override
public void onFailure(Object error) {
}
});
Conversation Default Settings
Kommunicate provides some parameters to configure the conversation rules when it is created. These parameters can be used to override the conversation rules you have set from the dashboard. You can set it by following codes. The setting will be effective from the next conversation user created by clicking "Create New Conversation" Button on Conversation List Screen.
Sample Codes to update the settings:
Kotlin
If you are using Kotlin:
KmSettings.setDefaultBotIds(botIds: List<String>)
KmSettings.setDefaultAgentIds(agentIds: List<String>)
KmSettings.setDefaultAssignee(assigneeId: String)
KmSettings.setDefaultTeamId(teamId: String)
KmSettings.setSkipRouting(isSkipRouting: Boolean) // pass true or false based on your requirement.
Java
If you are using Java:
KmSettings.setDefaultBotIds(List<String> botIds)
KmSettings.setDefaultAgentIds(List<String> agentIds)
KmSettings.setDefaultAssignee(String assigneeId)
KmSettings.setDefaultTeamId(String teamId)
KmSettings.setSkipRouting(boolean isSkipRouting) // pass true or false based on your requirement.
Details about the supported parameters:
Parameters | Type | Default Value | Descriptions |
---|---|---|---|
defaultAssignee | String | Configured routing rules for agents from dashboad | You need to pass the agentId/botId. If nothing is passed the default agent will automatically get selected. NOTE: You need to pass "skipRouting": true with defaultAssignee parameter if you have assigned a default assignee from the conversation rules section. |
defaultTeamId | String | All conversations will be assigned to default team | Assign conversations to a particular team by passing teamId and the conversation assignment will be based on your assigned team rules. Get team ID from teammates section. |
defaultBotIds | [String] | Configured routing rules for bots from dashboard | You can pass the default bots that you want to be present in every new conversation created. |
defaultAgentIds | [String] | Configured routing rules for agents from dashboard | You can pass the default agents that you want to be present in every new conversation created. |
defaultSkipRouting | Bool | false | If you pass this value true then it will skip routing rules set from conversation rules section. |
You can reset the existing default conversation settings by using below code:
KmSettings.clearDefaultSettings()
Update Conversation
Update Conversation Assignee
Use the below method to update the Assignee for a conversation
Kotlin
If you are using Kotlin:
KmSettings.updateConversationAssignee(
context = context,
conversationId = conversationId, // Either clientConversationId or conversationId of the conversation is required
clientConversationId = clientConversationId,
assigneeId = newAssigneeId,
callback = object : KmCallback {
override fun onSuccess(o: Any) {
// Successfully updated
}
override fun onFailure(o: Any) {
// Failed to update
}
}
)
Java
If you are using Java:
KmSettings.updateConversationAssignee(context,
conversationId, //Either clientConversationId or conversationId of the conversation is required
clientConversationId,
newAssigneeId,
new KmCallback() {
@Override
public void onSuccess(Object o) {
//Successfully updated
}
@Override
public void onFailure(Object o) {
//Failed to update
}
});
Update TeamId
Use the below method to update teamId for a conversation
Kotlin
If you are using Kotlin:
KmSettings.updateTeamId(
context = context,
conversationId = conversationId, // Either clientConversationId or conversationId of the conversation is required
clientConversationId = clientConversationId,
newTeamID = newTeamId,
callback = object : KmCallback {
override fun onSuccess(o: Any) {
// Successfully updated
}
override fun onFailure(o: Any) {
// Failed to update
}
}
)
Java
If you are using Java:
KmSettings.updateTeamId(context,
conversationId, //Either clientConversationId or conversationId of the conversation is required
clientConversationId,
newTeamId,
new KmCallback() {
@Override
public void onSuccess(Object o) {
//Successfully updated
}
@Override
public void onFailure(Object o) {
//Failed to update
}
});
Update Conversation Info
Use the below method to update conversation info for a conversation.
Kotlin
If you are using Kotlin:
KmSettings.updateConversationInfo(
context = context,
conversationId = conversationId, // Either clientConversationId or conversationId of the conversation is required
clientConversationId = clientConversationId,
conversationMetadata = conversationInfo, // Map<String, String>
callback = object : KmCallback {
override fun onSuccess(o: Any) {
// Successfully updated
}
override fun onFailure(o: Any) {
// Failed to update
}
}
)
Java
If you are using Java:
KmSettings.updateConversationInfo(context,
conversationId, //Either clientConversationId or conversationId of the conversation is required
clientConversationId,
conversationInfo, //Map<String, String>
new KmCallback() {
@Override
public void onSuccess(Object o) {
//Successfully updated
}
@Override
public void onFailure(Object o) {
//Failed to update
}
});
Send Message
You can send message programatically using following methods.
Send Text Message
You can send a message to the conversation using MessageBuilder. Use the below code to send a simple text message to a user.
Kotlin
If you are using Kotlin:
MessageBuilder(context)
.setMessage("Hello there")
.setGroupId(123456) // where 123456 is the conversationId.
.send()
Java
If you are using Java:
new MessageBuilder(context)
.setMessage("Hello there")
.setGroupId(123456). //where 123456 is the conversationId.
.send();
Send Message With Attachment
To send an attachment type message, use the filePath of the attachment with the MessageBuilder as below.
Kotlin
If you are using Kotlin:
MessageBuilder(context)
.setContentType(Message.ContentType.ATTACHMENT.value)
.setGroupId(12345) // where 12345 is the conversationId.
.setFilePath("<the file's absolute path as string>")
.send()
Java
If you are using Java:
new MessageBuilder(context)
.setContentType(Message.ContentType.ATTACHMENT.getValue())
.setGroupId(12345). //where 123456 is the conversationId.
.setFilePath("<the file's absolute path as string>")
.send();
Send Message With Metadata
To send the extra imformation with a message as metadata, use the below code:
Kotlin
If you are using Kotlin:
val metadata = mapOf(
"key1" to "value1",
"key2" to "value2"
)
MessageBuilder(context)
.setMessage("Hello there")
.setGroupId(12345) // where 12345 is the conversationId.
.setMetadata(metadata)
.send()
Java
If you are using Java:
Map<String,String> metadata = new HashMap<>();
metadata.put("key1","value1");
metadata.put("key2","value2");
new MessageBuilder(context)
.setMessage("Hello there")
.setGroupId(12345) //where 123456 is the conversationId.
.setMetadata(metadata)
.send();
Send Message With Callback
To send a callback for the attachment upload progress and message sent event. Add the MediaUploadProgressHandler
in the send()
method as below:
Kotlin
If you are using Kotlin:
MessageBuilder(context)
.setContentType(Message.ContentType.ATTACHMENT.value)
.setGroupId(12345)
.setFilePath("the files absolute path in string")
.send(object : MediaUploadProgressHandler {
override fun onUploadStarted(e: ApplozicException?, oldMessageKey: String?) {
if (e == null) {
// the upload has started
}
}
override fun onProgressUpdate(percentage: Int, e: ApplozicException?, oldMessageKey: String?) {
if (e == null) {
// display this upload percentage on the UI
}
}
override fun onCancelled(e: ApplozicException?, oldMessageKey: String?) {
// the upload was interrupted, most of the times by the user
}
override fun onCompleted(e: ApplozicException?, oldMessageKey: String?) {
if (e == null) {
// The upload has finished
} else {
// The upload has failed, due to network error or server error
}
}
override fun onSent(message: Message?, oldMessageKey: String?) {
// The message containing the attachment has been sent to the server.
}
})
Java
If you are using Java:
new MessageBuilder(context)
.setContentType(Message.ContentType.ATTACHMENT.getValue())
.setGroupId(12345)
.setFilePath("the files absolute path in string")
.send(new MediaUploadProgressHandler() {
@Override
public void onUploadStarted(ApplozicException e, String oldMessageKey) {
if(e == null){
//the upload has started
}
}
@Override
public void onProgressUpdate(int percentage, ApplozicException e, String oldMessageKey) {
if(e == null){
//display this upload percentage on the UI
}
}
@Override
public void onCancelled(ApplozicException e, String oldMessageKey) {
//the upload was interrupted, most of the times by the user
}
@Override
public void onCompleted(ApplozicException e, String oldMessageKey) {
if(e == null){
//The upload has finished
}else{
//The upload has failed, due to network error or server error
}
}
@Override
public void onSent(Message message, String oldMessageKey) {
//The message containing the attachment has been sent to the server.
}
});
To fetch the unread count
Without opening the chat
If you want to get the unread count without opening the chat, you can use this code:
Kotlin
If you are using Kotlin:
AlTotalUnreadCountTask(context, object : AlTotalUnreadCountTask.TaskListener {
override fun onSuccess(unreadCount: Int?) {
Log.d("$unreadCount")
}
override fun onFailure(error: String?) {
}
}).execute()
Java
If you are using Java:
new AlTotalUnreadCountTask(context, new AlTotalUnreadCountTask.TaskListener() {
@Override
public void onSuccess(Integer unreadCount) {
Log.d(String.valueOf(unreadCount));
}
@Override
public void onFailure(String error) {
}
}).execute();
Note: This will fetch the unread count from server.
After opening the chat
If you want to get the unread count after opening the chat, you can use this code:
Kotlin
If you are using Kotlin:
MessageDatabaseService(context).totalUnreadCount
Java
If you are using Java:
new MessageDatabaseService(context).getTotalUnreadCount();
Note: This will get the unread count from database without any server call.
Rich Message
Rich message provide a better overall conversational experience to the users, make the interface look pretty, they also drive more actions from your users and provide a good conversational experience. There are a variety of response types to choose from. For example, you can show images, play videos, provide buttons, list, forms, or card carousels.
Refer the following link to use rich messages in Kommunicate.