article by Frank Nimphius, September 2020
In this article I explain how to implement a feedback feature for answers to frequently asked questions.
As with many article on Oracle techExchange, there are a couple of things you will learn
- Formatting messages using an Apache FreeMarker array
- Defining answers as regular intents
- Adding icons to Common Response component actions
- Using a delegate object on the Oracle Web SDK
- Using CSS to customize the Oracle Web SDK rendering
The images below show the final product of this article. As an example I used frequently asked questions about Oracle Digital Assistant. The "thumb up" and "thumb down" icons are actions that a user can use to provide feedback. If the user does not want to provide feedback, then she could continue the conversation with a next message. The design goal of this implementation is to not be annoying by forcing the user to provide feedback. Providing feedback is made optional.
Disclaimer: Dependent on when you read this articles, the answers to questions in the screenshots may have changed or been updated.
The user is free to choose whether she wants to provide feedback or not. If she wants, then she would press one of the provided icons (which you choose how they look). Otherwise she would simply send another message that will be passed to the intent engine.
The image above shows a conversation the user continued without providing feedback. The conversation below then had the user clicking the thumbs-up button. The sample for this article prints a message in response to the user selected action button. In your production bot, the selected action should lead to a custom component call that then logs the user feedback so you can improve your chatbot.
The BotML (YAML) Code
All code in this sample is in BotML. Shown in the image below is the System.Intent component state. The System.Intent component state has an actions transition defined for all intents that are regular intents that start a conversation and no answers to a question. The example only has the unresolvedIntent defined for this. All other regular intents that get resolved are considered an answer to a question being asked by a user. Those intents follow the next transition to the prepareAnswerAndFeedback state. For an explanation of what answer intents are and when to use them compared to when to use regular intents for answering questions, see this article.
The state shown in the image below defines an array using Apache FreeMarker expressions. The array is saved in the answerWithFeedback variable and contains items with text added and blank items. The blank items mark the end of a paragraph. So basically I am formatting a message into paragraphs without using markup or encoded line-break characters,
The answer to a question is displayed by a System.CommonResponse component. The System.CommonResponse component iterates over the array that got created in the previous dialog flow step to print the message. For this it has the iteratorVariable pointing to the answerWithFeedback variable and its separateBubbles property set to false. This way multiple lines of the array get printed in a single speech bubble.
Two actions Ok and Bad are used for the user to provide feedback. The action items use resource bundle strings for their labels. Notice how the labels are printed as a single blank character for when the message channel is the Oracle Web SDK (websdk). This way the label is used by all messengers that e.g. don't support icons on action items and buttons. If you use a messenger that does support icons, for which you don't want the labels to show, you could add the messenger channel to the expression that checks whether or not the label should be printed as a blank character.
In the image below, I use a reference to pixabay.com for the thuumb-up and thumb-down icons. In your production environment you should use your own images that you store on an Internet facing server or a content delivery network (CDN).
Notice the three actions transitions defined for the System.CommonResponse component state.
- negativeFeedback – the transition is followed when the user presses the "thumb-down" action
- positiveFeedback – the transition is followed when the user presses the "thumb-up" action
- textReceived – the transition followed when the user doesn't select one of the buttons but types a new test message
The dialog flow state shown in the image below handle the three transition types. For the feedback options you replace the System.Output components with custom components that report the user feedback to a backend system for you to improve the answers if needed. The handleTextReceived dialog flow state prints a confirmation message to then direct the flow to the System.Intent component state to pass it to the intent engine.
Intents and Resource Bundles
The answers to print response to a question are saved in resource bundles, which means they can be translated if needed. The intent names are unique and can be used as the key name for a resource bundle string.
The image below shows a resource bundle definition. Note that the resource bundle strings are created in the User-Defined tab.
The answer for an intent is accessed when creating the array for the formatted message. To access the resource bundle content for an intent you use ${rb(iResult.value.intentMatches.summary[0].intent)}.
Note: "rb" is the name of the variable of type "resourcebundle" that you need to define in your dialog flow. "iResult" is the name of the "nlpresult" variable and is also referenced from the System.Intent component.
Oracle Web SDK client configuration
Two settings are required for the Oracle Web SDK to work as shown in the initial set of screenshots.
settings.js
The settings.js file that holds the web SDK configurations in the sample provided with the Oracle Web SDK download needs a delegate object that responds to the postback message. The postback message is sent when a user presses the thumb-up and thumb-down buttons. The beforePostbackSend function highlighted in the image below allows you to modify postback messages. In this example, it looks for answers that have a single blank character. If so, the function does not send the message to the server but re-routes it to Bots.sendMessage() as a hidden message.
Note: What the delegate object function in the image above does is to hide a blank message bubble. The blank message bubble would otherwise displayed when a user selects the thumb-up or thumb-down button. The function suppresses this empty bubble by sending a hidden user message. This function is not needed if you wanted to display a label and an icon. (see: "Alternative solution" later in this article)
index.html settings
You could run the sample without changing the index.html file. All changes that are required are those in the settings.js file. Without the changes in the index.html file, the buttons with the thumb-up and thumb-down actions will be rendered in a vertical orientation. The style information show below change the icons so they can be laid out next to each other as shown in the image at the beginning of the article.
Alternative solution
Alternative to displaying buttons just with a label you can display the buttons with an icon and a label. In this case you don't use the Apache FreeMarker expression in the showAnswer state to conditionally set the label to a blank character. Instead you always add the label as read from the resource bundle.
Also, the beforePostbackSend() function in the settings.js file can be left empty because no special handling is required.
Last, but not least, the index.html does not require any styling as you would need the buttons to be vertically aligned to allow the label to be placed next to the icon
Downloads
-
Import the skill
-
Train the model
-
Run the sample in the integrated conversation tester. Start by "what is an API call" and then "tell me about pricing"
-
Configure your settings.js and (optional) index.html file of the web SDK implementation (sample) as explained in this article
- Run sample in web messenger
Related Content
Oracle Native Client SDK References & Downloads
Oracle Web SDK product documentation (all you need to know)
TechExchange: Use font awesome and a custom component to create an icon menu for the Oracle Web SDK
TechExchange: Oracle Digital Assistant Web SDK customization and programming examples
