KnowledgeBase

A chatbot is a great way to provide help and information. Users can ask questions to your bot conversationally, and the bot can respond with answers and links to relevant content.

Information like this is provided to the bot through a Web Responder, which normally calls a web API built by you or a third-party. But with the KnowledgeBase feature, you don’t have to build your own API or host your information yourself. You can simply provide your content and links in a Google Sheet.

With that content, the BotCentral platform builds a custom API that you can call from a Web Responder. Let’s try it.

Create a Google Sheet for Your Content

In Google Sheets, create a new sheet with at least the following columns:

  • id — an integer, usually just the row index
  • title — an article title; works best if it is phrased as a question the user might ask
  • summary — a short answer, 80 characters or less
  • detail — a longer answer, but still under 350 characters
  • tags — a comma-separated list of relevant terms

These columns will be indexed by the platform, to help determine which item is the most appropriate answer for a user’s question. You can also add as many additional columns as you like. You can bring any of these into your chat conversation through the Web Responder, but their content won’t be indexed for output selection.

For this tutorial, we’ll be using this example sheet, with content adapted from our Frequently Asked Questions. You can see in the example that we have additional columns defined for other types of content we might want to add later.

Be sure to set the Share settings on your Google Sheet to Anyone with the link can view.

Create a KnowledgeBase DataSource

First, select the Knowledge feature from the main menu and click Add DataSource.

../_images/menu-kb-create-new.png

Give the new DataSource a relevant name and select KnowledgeBase for the Type. Paste in the sharing link from the Google Sheet.

../_images/kb-basics.png

When you click the Add button, some new fields appear.

../_images/sheet-added1.png

The URL provided in Search by Phrase is the one you are most likely to use for creating your Web Responder.

Testing Your KnowledgeBase Import

Before setting up your responder, it’s a good idea to test your import. On the left side of the screen you can try out search strings (user inputs), and the JSON that the API is going to return to your responder.

../_images/test-kb-by-phrase.png

Building a KnowledgeBase Responder

Now it’s time to build a Web Responder that calls the KnowledgeBase API. Start by going back to Bots from the main menu and selecting (or creating) the Bot you want to use. Then add a new Responder.

../_images/create-kb-responder.png

Give the Responder a relevant Name.

Calling the KnowledgeBase API

The Webhook is the URL provided by the KnowledgeBase builder, up to the question mark.

That is, if the URL is:

http://dataservice.botcentralapi.com/knowledge-0.1/articles/phraseSearch?source=349875kh340985k2lh59093h3k49&phrases=

Use this:

http://dataservice.botcentralapi.com/knowledge-0.1/articles/phraseSearch

In the Params section, you need two parameters.

  • Key source
    • Value the source parameter from the URL — for example, in the URL above, the source is 349875kh340985k2lh59093h3k49
  • Key phrases
    • Value {$query}

This will search the content from the Google Sheet for the value of {$query}, which is the user’s most recent input.

For Method, select GET.

Parsing KnowledgeBase Results

For this example, we’re going to use Button tiles for the Result Type. This returns some text in a normal chat bubble, and then a button.

If you have more complex content, like multiple links to additional content, you may want to use the Structured Tile.

../_images/kb-button-tile.png

In the first input field, we have:

{$.successResult.success[i].title} {$.successResult.success[i].detail}

The {$.successResult.success} object holds all the results from searching the KnowledgeBase content, and [i] lets you iterate over those results. The identifier after that specifies a column label from the Google Sheet. So, in this case we’re going to send the question (.title) and the long answer (.detail) to the user. If you wanted to, you could include other columns, like .summary.

Next we’ll add a button that links the user to the relevant docs, using the contentURL column from the Google Sheet.

Name
View Docs — this is the button label
Type
Web URL
CallBack
{$.successResult.success[i].contentURL}

If you had multiple links (for example: text content, video, audio), you could create multiple buttons.

Now you have a responder that will return results from your custom KnowledgeBase API.

Calling the KnowledgeBase Responder

Now that we have a working Responder, we just need to create a Message to call it. This is very easy.

../_images/kb-default-message-basics.png
Name
anything relevant
Type
Default Search — This message will be triggered if user input does not match a pattern or an intent.
Content Type
Dynamic
Responder Name
the name of the Responder

And now the Bot will respond with relevant answers to user questions.

../_images/test-kb-phone.png

Dealing with Bad Questions

But what happens if someone asks a question, but it doesn’t fit anything in your knowledge base? Right now, it’s a little clumsy.

../_images/kb-message-error.png

We can solve this with a little Postprocess Code. We’ll just check how many results were returned by the Web Responder — if it’s none, we’ll trigger a help message.

../_images/no-kb-results-postprocess.png
var results = botContext.getResponderResultsCount();
botContext.printDebugMessage('FAQ Results Count = ' + results);

if (results < 1){     // no results
  botContext.setTriggerNextMessage('FAQs Menu');
}

This will trigger the FAQs Menu message, which we now need to create. It will use Quick Replies to give the user some options of things to learn about.

../_images/faq-menu-basics.png

We’ll give it the pattern help*, so the user can access it directly by typing help or help me!.

Then give it a few static messages to deliver before the Quick Replies.

../_images/faq-menu-content.png

And then here is where it gets interesting. We’re going to give each of the quick replies a title (which the user will see) and then a payload, which the Bot will see. These will be interpreted as regular inputs, so they’ll be responded to as if the user is asking the question — and the right answer from the Knowledge Base will get returned.

../_images/faq-menu-quick-replies.png

Here’s the ones we’re using for our FAQ:

Title Getting Started
Payload how to get started
Title Patterns
Payload using patterns
Title Intents
Payload how to use intents
Title Bot Export
Payload how to export a bot
Title Debugging
Payload how to use the debugger

Now our Bot responds to “bad” questions with a helpful Quick Reply menu.

../_images/kb-bad-message-good-result.png