Conversation
In this section you will learn how to create and launch the conversation.
Create and Launch Conversation
One of the easiest ways to create and launch the conversation is to use the below method:
// Pass an instance of the current UIViewController in the 'from' argument.
Kommunicate.createAndShowConversation(from: self) { error in
guard error == nil else {
print("Conversation error: \(error.debugDescription)")
return
}
// Success
}
- If there are no conversations present, then this method will create a new conversation where the default agent and the logged in user will be present.
- If a conversation is already there, then it will open that conversation.
- In case there are multiple conversations present then the conversation list will be shown to the user.
- Please note that the Single Threaded Configuration will not be taken into account.
For passing agents or bots, you’ve to check out the New Conversation section
If you want to customise it like you want to create your own flow, then check out the Conversation
section below.
Conversation
Using these method you can create your own custom conversation flow. Let's say you want to create a new conversation every time when the user clicks on support, then use the API mentioned in the New Conversation
section below.
New Conversation
To create a new conversation, use createConversation
method as shown below. It allows you to create a new conversation by combining different options using KMConversationBuilder
.
let kmConversation = KMConversationBuilder()
// Optional. If Agent Id is not set, then default agent will
// automatically get selected. AGENT_Id is the email Id used to signup
// on Kommunicate dashboard.
// To add the agents to conversations directly pass the AgentId parameter
.withAgentIds( ["<AGENT_IDS>"])
// Using BotIds parameter the bots can be added to the conversations
.withBotIds(["<BOT_IDS>"])
// To set the conversation assignee, pass AgentId or BotId.
.withConversationAssignee("<AGENT_ID/BOT_ID>")
// To pass metadata
.withMetaData(["key":"value"])
// To set the custom title
.withConversationTitle("Support query 1")
// If you pass useLastConversation as false, then a new conversation will be created everytime. If you pass useLastConversation as true, then it will use old conversation which is already created with this data.
.useLastConversation(false)
//To assign the conversation to a team, pass a team Id.
.withTeamId("<team id>")
.build()
Kommunicate.createConversation(conversation: kmConversation) { result in
switch result {
case .success(let conversationId):
print("Conversation id: ",conversationId)
// Launch conversation
case .failure(let kmConversationError):
print("Failed to create a conversation: ", kmConversationError)
}
}
Note: When
useLastConversation(true)
is used, it overrides the Single Threaded configuration from the dashboard. Conversely, whenuseLastConversation(false)
is employed, the Single Threaded conversation takes precedence.
Create Conversation with Pre-Chat
You can add Pre-chat Lead Collections from the Pre-Chat Lead Collection section in the dashboard. This feature allows you to gather configured data before initializing a conversation, displaying a screen to collect the necessary information before the chat begins.
Note: This function handles both login and building the conversation, so you don't need to perform login separately.
Here is the code for creating a conversation with pre-chat:
let kmConversation = KMConversationBuilder()
// Optional. If Agent Id is not set, the default agent will
// be selected automatically. AGENT_ID is the email Id used to sign up
// on the Kommunicate dashboard.
// To add agents to the conversation, pass the AgentId parameter
.withAgentIds(["<AGENT_IDS>"])
// To add bots to the conversation, pass the BotIds parameter
.withBotIds(["<BOT_IDS>"])
// To set the conversation assignee, pass AgentId or BotId
.withConversationAssignee("<AGENT_ID/BOT_ID>")
// To pass metadata
.withMetaData(["key": "value"])
// To set a custom title
.withConversationTitle("Support query 1")
// If useLastConversation is set to false, a new conversation will be created every time.
// If set to true, it will use the last conversation created with this data.
.useLastConversation(false)
// To assign the conversation to a team, pass a team Id
.withTeamId("<TEAM_ID>")
.build()
Kommunicate.createConversationWithPreChat(
appID: <APP_ID>, // Pass your Kommunicate Application ID
conversation: kmConversation,
viewController: self,
completion: { error in
if error != nil {
print("Error while launching conversation: \(error.localizedDescription)")
}
}
)
Open Particular Conversation
Open any particular conversation by passing the conversationId
and reference to current view controller. You will get the conversationId after creating a conversation as described in the New Conversation section.
Kommunicate.showConversationWith(
groupId: conversationId,
from: self,
showListOnBack: false, // If true, then the conversation list will be shown on tap of the back button.
completionHandler: { success in
print("conversation was shown")
})
Open Conversation With Prefilled Text
The prefilled text can be set while opening a conversation. This will be shown in the input text bar, so the user has to tap the send button instead of typing a message. This will be useful if you are launching a chat from a particular screen where you'll know what a user will be typing. We've added this in the showConversationWith
API as shown below:
Kommunicate.showConversationWith(
groupId: conversationId,
from: self,
prefilledMessage: "This message will be prefilled in the input text bar",
completionHandler: { success in
print("conversation was shown")
}
)
Open Conversation List
To open a list of conversations use below method. Reference to current view controller needs to be passed.
Kommunicate.showConversations(from: self)
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 Code to update the Settings:
Kommunicate.defaultConfiguration.defaultAssignee = "your assignee id"
Kommunicate.defaultConfiguration.defaultTeamId = "your team id"
Kommunicate.defaultConfiguration.defaultBotIds = ["botid"] // replace it with your bot Id list
Kommunicate.defaultConfiguration.defaultAgentIds = ["agent ids"] //replace it with your assignee id list
Kommunicate.defaultConfiguration.defaultSkipRouting = true/false //The above changes will only function if this condition is true.
Note: Add these linese either in AppDelegate
didFinishLaunchingWithOptions
method or before creating the conversation or navigating to conversation list screen.
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 this code:
Kommunicate.defaultConfiguration.clearDefaultConversationSettings()
To get unread message count
To get the unread count you need to import the module like this import KommunicateCore_iOS_SDK
and use the below code
let unreadCount = ALUserService().getTotalUnreadCount()
Send a message programmatically
You can send a message programmatically, it will be useful when you want to send a message on the user’s behalf. The following code snippet shows how you can send a message and open that conversation where the message was sent.
let conversationId = "<pass a conversation ID>"
let message = KMMessageBuilder()
.withConversationId(conversationId)
.withText("Message from the user.")
.build()
Kommunicate.sendMessage(message: message) { error in
guard error == nil else {
print("Failed to send message: \(String(describing: error?.localizedDescription))")
return
}
Kommunicate.showConversationWith(groupId: conversationId, from: self) { shown in
print("Conversation shown: \(shown)")
}
}
Sync conversations on app launch
Below code is used to sync conversations from server whenever app is launched. Put below lines in your AppDelegate
's didFinishLaunchingWithOptions
method.
KMPushNotificationHandler.shared.dataConnectionNotificationHandlerWith(Kommunicate.defaultConfiguration)
let kmApplocalNotificationHandler: KMAppLocalNotification = KMAppLocalNotification.appLocalNotificationHandler()
kmApplocalNotificationHandler.dataConnectionNotificationHandler()
Update Conversation
You can update the assignee , teamId and metadata of a conversation by using this method. First Create a conversation object by using KMConversationBuilder
.
1. To Update Conversation Assignee of the conversation
let conversationId = "your_conversation_id"
let assigneeId = "your_assignee_id"
let conversation = KMConversationBuilder().withClientConversationId(conversationId).withConversationAssignee(assigneeId).build()
2. To Update Team Id of the conversation
let conversationId = "your conversation id"
let teamId = "team id needs to be updated"
let conversation = KMConversationBuilder().withClientConversationId(conversationId).withTeamId(teamId).build()
3. To Update Conversation Metadata of the Conversation
let conversationId = "your conversation id"
let metaData = ["key1":"value1", "key2": "key2", "key3":"value3"]
let conversation = KMConversationBuilder().withClientConversationId(conversationId).withMetaData(metaData).build()
Upon creating the conversation object pass it to below bethod:
Kommunicate.updateConversation(conversation: conversation) {response in
switch response {
case .success(let clientConversationId):
print("conversation is updated successfully")
break
case .failure(let error):
print("failed to update conversation")
break
}
}
Note: Don’t try to update the assignee and teamId in a single call. You should use this method to update either assignee or teamId at a time.
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.