Work with conversational assistants (chatbots)

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 texts
quick_replies: Messages customers can select from available response buttons, or quick replies
mll: 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 text
Action: Button responses from quick replies
MLLNode: 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`

You 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()`

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 newConversationId here) 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.

Conversational assistant message template types

📘JSON message template types

Select a conversational assistant by id

Select the default conversational assistant

Store the id of the final conversation in a variable

Set up a listener

Implement makeAnAssistant()

Notes

📘
JSON message template types

Select a conversational assistant by `id`

Implement `makeAnAssistant()`