article by Frank Nimphius, March 2021
repost May, 2021
The concept of convention over configuration as a paradigm in framework development to facilitate the decisions developers must make, can be implemented in Oracle Digital Assistant to build skills that answer frequently asked questions.
This article explains how to create frequently asked question chatbots (skills) without coding by following a set of naming convention rules.
The starting point of this approach is a skill template sample that I provide at the end of this article. The skill contains all of the dialog flow coding required to make this work.
Note: This article does not explain how the provided skill template works but how to use the template for building custom Frequently Asked Questions skill bots. To understand how the template, and thus the "programming by convention" implementation works, please read the commends added to the BotML in the dialog flow.
About Building A Frequently Asked Questions Skill
Oracle Digital Assistant provides answer intent and regular intent to create chatbots that answer frequently asked questions.
- Answer intents are associated with a predefined response that is displayed to a user when the intent is resolved for a user message. The benefit of answer intents is that they use true NLP and machine learning and don't require a dialog flow.
- Regular intents are like answer intents except that they require developers to write a dialog flow to return the response to a question. The benefit of regular intents is that developers can perform additional tasks before or after displaying the answer.
The skill template introduced in this article uses both approaches, answer intents and regular intents to build chatbots that handle frequently asked questions such that the questions are multi-language enabled and that you can handle answers separate for different channels if you want so (adaptive bot design video)
Question – Answer Types Supported By the Skill Template
The template skill provides a convention for the following 4 answer types
- simple text message
- text message that can be optimized for different messenger channels (adaptive bot responses)
- text message with attachment (video,audio,image) that that can be optimized for different messenger channels (adaptive bot responses)
- text message with follow-up URL link that can be optimized for different messenger channels (adaptive bot responses)
Skill template benefit
Developers usually struggle creating dialog flows.
So to make it easy to build a skill for frequently asked questions, I created a framework in a template that has all the required dialog flow code in it.
So, to build a skill handling frequently asked question with the 4 types fo answers I mentioned before, you don't need to code!. All you do is to follow a naming convention and create answer strings in resource bundles.
Why optimizing answers for a channel?
Even if you don't yet have a reason to print different responses to a question for a channel, you will find some soon.
One reason for optimization is formatting, which different channels handle differently and many don't even support.
Another reason is the support of labels, which can be different in the allowed length for different channels.
Or, for text only channels like SMS, you want to keep answers shorter than for messengers like the web of Facebook.
FAQ Development By Convention
To get started, you need to import the FAQ Framework Skill that you can download from the end of this article to your own Oracle Digital Assistant instance. In the screenshot below I cloned the template skill to FAQ Framework Skill Demo.
Naming Convention For Intents
This article is about "programming by convention", which means that the framework I created in the sample skill will require a specific naming scheme to do the right thing. The naming scheme the sample skill expects to be used for intents is shown below:
- Simple text responses: ans.intent_name
- text response with adaptive response capabilities: reg.intent_name
- text response with attachment and adaptive response capabilities: reg.attach.intent_name
- text response with URL external web reference and adaptive response capabilities: reg.url.intent_name
This means that e.g. to define an intent for a question / answer pair that should have an attachment, the intent name must be reg.attach.intent_name, where "intent_name" needs to be replaced by the name you want to give to the intent.
Similar, to create a question / answer pair that display an external URL link at the end of the answer, you use reg.url.intent_name as the intent name format.
The image below shows 4 intents that I created in the demo skill you can download at the end of this article. The demo skill has one intent name created per before mentioned FAQ type:
- ans.aboutSample – An intent that uses an Oracle Digital Assistant answer intent to print a simple answer for a question
- reg.attach.aboutDigitalAssistant – An intent that returns a response with an attachment (image in this sample)
- reg.tutorial – An intent that returns a message that can be formatted for a specific messaging client
- reg.url.documentation – An intent that returns a message that has an external URL reference pointing to the Oracle Digital Assistant documentation
Creating utterances
A brain that has not learned anything is just a brain.
For each of the intents you create following the convention you need to add good utterances. Utterances represent how users would ask for a specific answer.
You don't need to know the exact question users would ask, but your utterances need to get close to how a typical user of your bot would try getting a specific answer.
I suggest you create 50 utterances for each intent and then use Trainer Tm as a model. Note that Trainer Tm is needed for answer intents. To learn what makes a good utterance, please read Training your NLP model – Best Practices In Writing Utterances.
Creating 50 utterances may sound a lot. Here is an approach I am following. As shown in the image below, you would use the advanced inout mode for utterances for an intent. You then start with creating 5 – 10 utterances that should be as different as possible (the more, the better).
You then start creating a new variant for each using recommendations in the paper I linked above. So in my about sample intent, I did build
In between, you save the intents. Then you repeat creating new variations using synonyms, structure changes, different addressing of personas etc.
Once done adding utterances, you train the model using Trainer TM. For this you would press the Train button on the right upper corner of the page.
Initially, the "Train" button shows an exclamation mark, indicating that it is not trained, After training the skill, the "Train" button should look like in the image below.
Implementing the Simple Text Answer Type
In the demo skill, ans.aboutSample provides the simplest implementation for an answer. The answer will use a text message that gets stored in a resource bundle so it can be translated for use with other languages.
To create such a "simple message" implementation, you select the intent and type the answer directly into the intent's Answer field (see image below)
The message that will be displayed to the user after the user messaging e.g. "what is this sample about" will be:
"Programming by convention is a software paradigm that can be implemented in Oracle Digital Assistant using resource bundles and a good naming convention. This example shows you how to use programming by convention to create a Frequently Asked Question skill that supports 4 different types of answers."
Notice how easy this first implementation was.
Implementing the Advanced Text Answer Type
The advanced text type allows you to display different answers based on the messaging channel that a user uses. The answer could be formatted according the channel's capabilities or be shortened for messengers that don't support long strings (e.g. SMS).
To implement this answer, you need to create a resource bundle key, where the key name matches the name of the intent plus an additional ".answer" postfix. In the demo skill, the name of the intent to return an advanced response for is reg.tutorials. Therefore the name of the resource bundle string must be reg.tutorials.answer.
To create the resource bundle, you switch to the resource bundle panel and press the + key button
Note: the existing footerText message gets appended at the end of each message. You can customize the message to your needs.
Following the convention used in this skill template, the name of the resource bundle key must be: <name of intent>.answer. So for the intent name "reg.tutorial", you need to create a key with the name reg.tutorial.answer (dee image below)
The message you see in the image above is
{channelType, select,
websdk {The tutorials written for Oracle Digital Assistant are a great source of inspiration and learning and cover a wide range of topics suited for beginners and advanced users. You find the <b>Oracle Digital Assistant tutorials </b>at <a href='https://docs.oracle.com/en/cloud/paas/digital-assistant/tutorials.html'>Oracle Documentation Page</a>
}
other {The tutorials written for Oracle Digital Assistant are a great source of inspiration and learning and cover a wide range of topics suited for beginners and advanced users. You find the Oracle Digital Assistant tutorials at https://docs.oracle.com/en/cloud/paas/digital-assistant/tutorials.html
}
}
Resource bundle message explained
1. channelType: the argument passed by the skill. Possible values are websdk (Oracle web messenger), adroid (Oracle Android messenger), ios (Oracle IOS messenger), slack (Slack), msteams (MS Teams), twilio (Twilio/SMS), facebook (Facebook messenger), webhook (custom messenger channel), cortana (Cortana)
2. select: The "select" keyword is understood by the Oracle resource bundle implementation. It tells Oracle Digital Assistant, that different messages may be displayed based on the "channelType" value.
3. websdk: The sample renders a different message for when the messenger is "websdk". Here the text response uses HTML markup.
4. other: All messengers that are not explicitly mentioned in the resource bundle (so all except websdk in the sample) will return the text message that is defined as "other". This message is the default response and a fallback.
Note: You can add as many blocks like websdk in the message to display responses for a specific channel. If e.g. you wanted to add a different message for slack, you would use
{channelType, select,
websdk {The tutorials written for Oracle Digital Assistant are a great source of inspiration and learning and cover a wide range of topics suited for beginners and advanced users. You find the <b>Oracle Digital Assistant tutorials </b>at <a href='https://docs.oracle.com/en/cloud/paas/digital-assistant/tutorials.html'>Oracle Documentation Page</a>
}
slack { MY SLACK MESSAGE (!!!) The tutorials written for Oracle Digital Assistant are a great source of inspiration and learning and cover a wide range of topics suited for beginners and advanced users. You find the *Oracle Digital Assistant tutorials* at https://docs.oracle.com/en/cloud/paas/digital-assistant/tutorials.htm.
}
other {The tutorials written for Oracle Digital Assistant are a great source of inspiration and learning and cover a wide range of topics suited for beginners and advanced users. You find the Oracle Digital Assistant tutorials at https://docs.oracle.com/en/cloud/paas/digital-assistant/tutorials.html
}
}
———
Note: Rendering messages optimized for the current user channel is what I refer to as adaptive bot response design. If you are interested in the full story of adaptive design in Oracle Digital Assistant, watch the following video: adaptive bot design.
Testing
Yo can test the bot responses using the conversation tester in Oracle Digital Assistant skills. The tester can simulate different messengers (it does not emulate them, why the rendered response e.g. does not interpret HTML tags aded for the web).
The images below show the Frequently Asked Question response for a message sent from the Oracle Web messenger, from Slack and from Twilio / SMS. Note that for Twilio SMS, the message that gets displayed is read from the other section in the resource bundle string.
Oracle Web (HTML markup rendered in conversation tester but not interpreted. Will be interpreted when run in Web messenger)
Slack (markdown (e.g. *…*') rendered in conversation tester but not interpreted. Will be interpreted when run in Slack messenger)
Twilio SMS (uses "other" message)
Implementing the Advanced Text Answer Type With Attachment
The Frequently Asked Question response that returns an advanced text answer type with an attachment (image, video, audio) requires four resource bundle strings. According to the naming convention used by the framework skill template that you can download from the end of this article, the resource bundle strings need to be named as follows
- reg.attach.<name of intent>.answer
- reg.attach.<name of intent>.attachmentType
- reg.attach.<name of intent>.attachmentTitle
- reg.attach.<name of intent>.attachmentUrl
So, for the sample in the demo skill, the intent name is reg.attach.aboutDigitalAssistant, which means that, to implement a message with attachment, the following resource string keys need to be created
- reg.attach.aboutDigitalAssistant.answer
- reg.attach.aboutDigitalAssistant.attachmentType
- reg.attach.aboutDigitalAssistant.attachmentTitle
- reg.attach.aboutDigitalAssistant.attachmentUrl
Example: reg.attach.aboutDigitalAssistant.answer key
The message you see in the image above is. As with the advanced test message sample, it uses a select type to print the bot response according to the detected messenger type.
Here however, I've implemented a specific message for the web and the other message. The slack message is not present, which means that the slack channel would see the message defined for other.
{channelTye,select,
websdk{Oracle Digital Assistant (<b>ODA</b>) is a Platform as a Service (PaaS) service in Oracle Cloud Infrastructure (<b>OCI</b>). Using Oracle Digital Assistant, developers create custom chatbots (skills) that they combine into a concierge bot (digital assistant) for bot conversations that can span several business domains and understand natural language.}
other{Oracle Digital Assistant (ODA) is a Platform as a Service (PaaS) service in Oracle Cloud Infrastructure (OCI). Using Oracle Digital Assistant, developers create custom chatbots (skills) that they combine into a concierge bot (digital assistant) for bot conversations that can span several business domains and understand natural language.}
}
1. channelType: the argument passed by the skill. Possible values are websdk (Oracle web messenger), adroid (Oracle Android messenger), ios (Oracle IOS messenger), slack (Slack), msteams (MS Teams), twilio (Twilio/SMS), facebook (Facebook messenger), webhook (custom messenger channel), cortana (Cortana)
2. select: The "select" keyword is understood by the Oracle resource bundle implementation. It tells Oracle Digital Assistant, that different messages may be displayed based on the "channelType" value.
3. websdk: The sample renders a different message for when the messenger is "websdk". Here the text response uses HTML markup.
4. other: All messengers that are not explicitly mentioned in the resource bundle (so all except websdk in the sample) will return the text message that is defined as "other". This message is the default response and a fallback.
Example: reg.attach.aboutDigitalAssistant.attachmentType key
The attachment type key / value pair defines the type of attachment to be image, audio, video or file. In the demo skill, the attachment is of type image, so the resource bundle string looks like shown in the image below
Example reg.attach.aboutDigitalAssistant.attachmentTitle key
Attachments have a title. In the demo skill, I set the title to "About ODA" as shown in the image below
Note: If you wanted to display the title different when the answer is rendered on the web than when rendered on slack or elsewhere, you could set the text string as
{channelType,select,
websdk {About ODA – Web}
slack {About ODA – Slack}
other{About ODA}
}
Example reg.attach.aboutDigitalAssistant.attachmentUrl key
The Url key value defines the absolute URL of where the attachment (the image in the demo case) is accessible from.
Note: As with the attachment title, it is possible to use different images (or attachments in general) for different messengers. For this you would use the following key value
{channelType,select,
websdk {https://acme.com/path/image1.png}
slack {https://acme.com/path/image2.png}
other{About ODAhttps://acme.com/path/image3.png}
}
Question: Can you have different attachment types per channel? Yes, you can. Just use the select type key value in the channelType resource string
Testing
When testing the attachment question and answer, you will see a response similar to the response shown in the image below
Web Message
Slack message
Implementing the Advanced Text Answer Type With Url Reference
The 4th option for defining an answer is to use one with an URL reference. The naming convention to apply is
- reg.url.<name of intent>.answer
- reg.url.<name of intent>.url
- reg.url.<name of intent>.urlTitle
The demo skill has an intent named defined as reg.url.documentation. So, for this you need to create the following resource bundle keys
- reg.url.documentation.answer
- reg.url.documentation.url
- reg.url.documentation.urlTitle
Example: reg.url.documentation.answer key
Like before, the "answer" key name postfix indicates the key name that holds the answer to a question.
Note: As with advanced text messages and advanced text messages with attachment, you can use a select type expression as the resource bundle string to display different answers based on the channel (channelType).
{channelType, select,
websdk{The Oracle Digital Assistant product documentation is a <b>real bestseller</b>. It is accessible to everyone on the web and describes the Oracle chatbot platform in great detail. The documentation also offers numerous programming examples, which is why <b>it is an excellent learning resource even for beginners</b.}
other{The Oracle Digital Assistant product documentation is a real bestseller. It is accessible to everyone on the web and describes the Oracle chatbot platform in great detail. The documentation also offers numerous programming examples, which is why it is an excellent learning resource even for beginners.}
}
The demo skill uses one answer for all channels, just to showcase that it can be done and how it is done.
Example: reg.url.documentation.url key
The url key defines the external URL that users will be navigated to in a separate browser window or browser tab when pressing the URL button rendered below the answer.
Like with attachments and advanced text messages, the URL be defined using a select type if you wanted to use different URLs for different channels.
Example: reg.url.documentation.urlTitle key
The urlTitle key defines the label that goes on the URL button. Again, you can use a single label for all messengers, or define messenger specific buttons using the select type explained for advanced text message and advanced text message with attachment use cases.
One reason why you would want to create channel specific button labels is because different messengers support different length for the labels. So, if you experience a label getting copped by a messenger, you can simply add a resource string that prints a different label for this messenger then.
Testing
When you run the demo skill for the URL type answer, you should see the following response
Clicking the button, for the demo, directs you to the Oracle Digital Assistant product documentation page
Extending the FAQ Skill Template
You did not find the answer format you need? No problem, you can extend the template skill with you own implementation of an answer. Have a look at the BotML in the dialog flow and read the comments. You will easily understand how you can create your own answer formats.
When defining your own answer format, make sure you define a unique prefix for the intent names and resource bundle names. The naming should follow this format
reg.<your prefix>.<intent name>
Once you created your own custom answer format, you can create frequently asked questions with it just by creating intents and resource bundle keys.
Conclusion
Programming by convention is a new pattern that this article introduces for Oracle Digital Assistant. The idea of this pattern is to implement a skill such that developers who need to implement the functionality in their digital assistants only need to follow naming conventions for intents and resource bundle key names.
The example skill template and demo I provide with this article if for building Frequently Asked Question skills that provide 4 options for rendering the answer to a question. Using the "select" type expression in a resource bundle message, you can implement adaptive bot response design easily so that messages are displayed in an optimized manner for selected messengers.
Downloads
The starter skill that you configure with your intents and resource bundle keys
The demo skill that you can use to explore how to use the template skill. Its also the skill that I used for the screenshots in this article
Related Content
Oracle Digital Assistant Design Camp: Integrating Frequently Asked Questions (video)
TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube
