Work with conversational assistants (chatbots)
Learn how to work with conversational assistants (chatbots) with the Kustomer Core SDK.
Conversational assistants are chatbots in Kustomer that allow you to exchange automated messages with a customer to collect information or provide self-support opportunities before the customer connects with an agent over chat.
Conversational assistant message template types
JSON message template types
See Template types for Kustomer Chat message template types with sample JSON object templates and UI examples.
A conversational assistant sends chat messages with one of three message template types available in the Chat SDK:
text: Messages in plain text, or textsquick_replies: Messages customers can select from available response buttons, or quick repliesmll: Messages customers can select from a multi-level list with parent list items and children list items, or Multi-level Lists (MLL)
Chat message responses from the customer to the assistant use one of the following three formats:
String: Responses in plain textAction: Button responses from quick repliesMLLNode: Selection responses from a multi-level list
The assistant receives and processes the customer response. Based on the customer response, the assistant sends another message or a set of messages based on the configured conversational flow.
The assistant and customer exchange chat messages until the assistant either ends the chat or transfers the customer to a support agent.
Select a conversational assistant by id
idYou can select a specific conversational assistant by the assistant id. To learn how to find the assistant id, see Conversation assistant id in the Kustomer Help Center.
var assistantId = "123" // the ID of the chat assistant you want to use
Select the default conversational assistant
You can use the Chat Management: Settings to select a default conversational assistant for each brand. To learn how to set a default conversational assistant, see Default Assistant in the Kustomer Help Center.
assistantId = Settings.activeAssistant
Store the id of the final conversation in a variable
The id of the conversation you're going to make/use is set in makeAnAssistant(), further down the page. You'll need this to be able to use other core sdk methods with your conversation.
var theNewConversationId:String?
Set up a listener
Create a listener with KUSChatListener to tell you when a new chat message is received because of the conversation that was started with an assistant:
let listener = MyChatListener()
ChatProvider.shared.addChatListener(listener)
extension MyChatListener: KUSChatListener {
public func onChatMessageReceived(conversationId: String, chatMessage: KUSChatMessage) {
// a message was received for the assistant you created
if chatMessage.conversationId == theNewConversationId {
print("New message received for the assistant you created."+"\(chatMessage.description)")
}
}
}
Implement makeAnAssistant()
makeAnAssistant()Implement makeAnAssistant() to do the following:
- Get the active assistant and start dialog
- Gets the initial messages that the active assistant asks the user, which contain the data needed to render buttons and multi level list items for the first question that requires a user response
- Automatically replies with the last button, multi level list item, or the text "Orders"
- Gives you a conversation id (stored in
newConversationIdhere) you use just like without a chat assistant
func makeAnAssistant() {
let assistantId = Kustomer.getActiveAssistantID()
let startDialog = Kustomer.getActiveAssistantStartDialog()
var newConversationId: String?
ChatProvider.shared.getInitialMessages(assistantId: assistantId, startDialog: startDialog) { result in
guard case .success(let initialMessages) = result else {
return
}
// now populate your UI with `initialMessages`
// when you want to respond to the assistant, you want to respond to the last `initialMessage`.
// use `ChatProvider.shared.createConversation(...)` with the response the user selected
// te conversation will be created with the active assistant
// then in the completion callback you will get a conversation, with an id
// in this example, we will automatically respond to the chat assistant:
// this block gets called after the customer responds
let completion = { (result: Result<(conversation: KUSConversation, messages: [KUSChatMessage], customer: KUSCustomer?), KError>) in
guard case .success((let conversation, let messages, let customer)) = result else {
return
}
// you can add `message` to your UI here. or, you can add it in the `onChatMessageReceived` function. it will be passed to both
// we save the conversation id for use in the `onChatMessageReceived` callback
newConversationId = conversation.id
}
// get the last initialMessage
let respondTo = initialMessages.last!
// respond to this chat assistant
switch respondTo.templateType {
case .text:
// if the assistant is waiting on a text response, we send the string "Orders"
ChatProvider.shared.createConversation(firstCustomerMessage: "Orders", completion: completion)
case .mll:
// if the assistant is waiting on a multi level list response, we pick a random item from the available MLL responses
// get a random response for this message
let selected = respondTo.mllNode!.children!.randomElement()!
// use it to reply
ChatProvider.shared.createConversation(mllNode: selected, completion: completion)
case .quickReplies:
// if the assistant is waiting on a quick reply (button) response, we pick a random item from the available responses
// get a random response for this message
let selected = respondTo.actions!.randomElement()!
// use it to reply
ChatProvider.shared.createConversation(action: selected, completion: completion)
default:
break
}
}
}
Notes
Note 1: for buttons and multi level list items the user must reply with one of the provided options--free text won't progress the assistant.
Note 2: the initial messages of the chat assistant will be re-broadcast to your KUSChatListener after you send the first user response.
Note 3: only after you create the conversation with the first response will a conversation object (and conversation id) actually be created.
Updated almost 2 years ago