Add an article
An article is a focused piece of content (a message) on a single topic that you want to serve to consumers.
To add an article to a knowledge base
- Open the knowledge base, and click Add New in the upper-right corner.
- Specify the following basic settings:
- Title: Enter a complete sentence or question, e.g., "I can't remember my password." or, "Do we have a company org chart?" See farther below on this page for best practices.
- Intent Qualifiers: This field is only shown if you're using Knowledge Base intents. Intent qualifiers are alternative ways that people ask for the article, i.e., alternative ways to communicate the same intent. See farther below on this page for best practices.
- Intent: This field is only shown if the knowledge base is using Domain intents. Select the intent to associate with the article. See farther below on this page for best practices. If needed, you can use the Create intent option in the drop-down list to create the intent in Intent Builder from this location. Similarly, there's an Update training phrases link for updating the training phrases in Intent Builder from here.
- Summary: Enter a short response or message to be sent to the user. You can include web links, although depending on the channel they might not display correctly. For SMS/Messaging, you might need to show the URL by itself, not wrapped in HTML, since the HTML will be sent as plain text over these channels.
- Detail: This field can be used to include longer messages to the user. For messaging, it's recommended that you keep the responses as brief as possible.
- Category: To assign the article to a category, enter the category name. This lets you subsequently filter and find articles based on category in the Knowledge Base application.
- Tags: Tags are keywords, not sentences, that highlight the key noun(s) or word(s) in the title and intent qualifiers/training phrases. Tags can also be entities that you've defined in a domain in Intent Builder. To increase the accuracy of Knowledge Base search results, add tags. For example, for an article about health insurance, the tags should be "health", “insurance”, “benefits”. These should be words, not sentences.
If desired, click Advanced Settings, and specify the following:
- Content: Use this field to send a hyperlink. Enter the URL here, and then configure the bot with the Knowledge Base integration accordingly. For help, see the next section.
- Audio: Use this field to send an audio file. Enter the URL here, and then configure the bot with the Knowledge Base integration accordingly. For help, see the next section.
- Image: Use this field to send an image. Enter the URL here, and then configure the bot with the Knowledge Base integration accordingly. For help, see the next section.
- Video: Use this field to send a video. Enter the URL here, and then configure the bot with the Knowledge Base integration accordingly. For help, see the next section.
- Click Save.
Add content links
You can use the content links in the Advanced Settings of an article to send rich content (hyperlink, audio, image, and/or video) along with an article.
Details on how to set this up follow below.
Configure the article
First, in the Advanced Settings of the article, enter the URLs to send (1).
Configure the Knowledge Base integration in the bot
Next, open Conversation Builder and navigate to the Knowledge Base integration inside the bot that uses the knowledge base.
Verify that the appropriate knowledge base is selected (2), and then add custom data fields for the content links that you're using (3).
The "article" custom data field is added automatically when you add the Knowledge Base integration, but in this step you need to manually add additional custom data fields for the content links. For the values, specify the paths to the URL nodes in the JSON, like we've done in the image below.
For the names of the JSON nodes for the content links, see the JSON reference farther below in this topic.
Configure the dialog in the bot
Next, still in Conversation Builder, build out the applicable dialog to make use of the additional content (4), i.e., use the custom data fields as you require. (For help on displaying variables in interactions, see here.)
Preview the conversation
Use Conversation Builder's Preview tool or the Knowledge Base's Chat tool to preview the conversation and verify the content is returned and rendered as you expect.
To accomplish this, in the interaction that displays the article, we've configured the next action to be "end interaction" (not shown below). Then, we've added some post-process code to that same interaction. The code (shown below) checks whether the content link (URL) exists, and, if it does, it changes the interaction's next action to be the following interaction.
Train a knowledge base
To train a knowledge base, select the knowledge base, enter an utterance, and review the results. If you don't get any results for a particular utterance, you can adjust the filters by tapping the advanced search icon.
By default, the Search Settings are set to Intents and Fair Plus. This means that the algorithm will first see if there are any matches using our NLU, with a threshold of Fair Plus. However, if it doesn’t find any, it will attempt a text search as well. Because of this, you might see a message like "No intent matched. Performed text search. 3 results found." This means you should add some more training phrases to an article to improve your results.
If you don’t want the follow-up text search, you can change the Search Settings to "Intents Only" which will ONLY perform the intents search.
If you ONLY want to perform the text search, you can set the Settings to "All".
To add more training phrases (or intent qualifiers), you can manually add them to your article.
You can also use the Thumb Up and Down icons displayed in a search. Below is an example where the utterance returned some results. The preferred result was only a FAIR match. By tapping the Thumbs Up icon, you automatically add the current utterance to a Positive Learning set for this article. Tapping Thumbs Down does the opposite.
If you were to rerun the search, the article would return with a higher score.
If you look at the article details, in the Advanced Settings, you can see that the utterance has been added.
Beware of overtraining
Something to keep in mind when training in general, and using the Thumbs Up/Down icons specifically, is that because they are so easy to use, they are often misused. Often people use Thumbs Up for extremely specific or lengthy utterances that, although said by an end user, are not great training phrases because they would never match another user’s utterance. Over time, the addition of these utterances (often 50+ added) skew the results in a negative way. The same is true when using Thumbs Down. Anything over about 10 - 15 training phrases might begin to return false positives.
Test user input
Use the Debugger tool to feed user input directly into a knowledge base to test the NLU processing and content matching.
The Debugger tool works exactly like a Knowledge Base integration in a bot. So, if your search selections in the tool match how you've configured the bot, the results you see with the tool will be the same as those returned in a bot conversation. If you don't yet have a bot integrated with your knowledge base, the Debugger tool is also a way to test how the bot will behave once it is.
The Debugger tool is also the way to see the JSON that's returned by the search.
To test user input
Open the knowledge base, and click in the lower-right corner.
Specify the following:
In the results, the JSON of the matched article is displayed. You can examine the "title" to see which article has been matched.
Chat with a bot linked to a knowledge base
If you have a bot linked to your knowledge base via a Knowledge Base integration, in the Knowledge Base application, you can feed test user input to the bot to see if it matches, returns and renders content as you'd expect.
If you're just getting started with knowledge bases and want to try using this tool, we recommend you create a bot using the Simple FAQ bot template and connect it to your knowledge base. Most of the bot development work is already done. You only need to update the integration in the bot so that it uses your knowledge base, as shown in the image below.
To chat with a bot linked to a knowledge base
- If you haven't already done so, in Conversation Builder, create a bot that includes a Knowledge Base integration that uses the knowledge base you want to test.
- Return to the Knowledge Base application, and open the knowledge base.
- Click (Chat) in the lower-right corner.
In the Preview panel, select the bot to use.
Begin to feed test user input to the bot to see how it responds.
Find articles with a specific tag
- In the knowledge base, click (Tags) in the lower-right corner.
In the Tags panel, select the tag to highlight it. You can repeat this step as needed if you're looking for articles assigned to multiple tags.
The result list is updated to include only the articles with the selected tags.
Find articles assigned to a specific category
- In the knowledge base, click (Categories) in the lower-right corner.
In the Categories panel, select the category to highlight it. You can repeat this step as needed if you're looking for articles assigned to multiple categories.
The result list is updated to include only the articles assigned to the selected categories.
The following table identifies the JSON node for article information that's often needed when you're integrating the knowledge base with a bot.
If you're looking for the name of a node not listed here, you can use the Knowledge Base's Debugger tool to identify it; the tool displays the JSON that's returned by an article search.
|Name of UI field||Name of JSON node|
|Content Links > Content||contentURL|
|Content Links > Image||imageURL|
|Content Links > Video||videoURL|
|Content Links > Audio||audioURL|
To increase the quality of your content matches, follow the best practices below.
For more best practices when training and tuning NLU, see here.
Titles, intent qualifiers, and training phrases
Use full sentences, e.g., “How do I reset my password?”
Use a simple, concise sentence, not multiple sentences. For example, "How do I activate my card?" is much better than, “How do I activate my card? I am having trouble at the ATM. Can you help me?” Multiple sentences increase your risk of false positives.
When adding intent qualifiers or training phrases, add 10 - 15 per article. Exceeding this likely means that you have overtrained, which might lead to false positives.
The intent qualifiers or training phrases should be relatively generic. If they are too specific, the likelihood they will match a consumer’s utterance will be slim. Since consumers can phrase their questions in many ways, make sure your intents are broad to allow the NLU a chance to match as many possible versions of the sentence as possible.