AWS Machine Learning Blog

Create a Question and Answer Bot with Amazon Lex and Amazon Alexa

July 2022: Update v5.2.0 – Intent and Slot matching, Kendra Redirect, Import/export CLI, and more. See New features

ANNOUNCEMENT
QnABot on AWS is now an official AWS Solution Implementation.
To learn more about secure one-click deployment with the solution’s AWS CloudFormation template, select Get Started

Your users have questions and you have answers, but you need a better way for your users to ask their questions and get the right answers. They often call your help desk, or post to your support forum, but over time this adds stress and cost to your organization. Could a chat bot add value for your customers? Interestingly, a recent poll shows that 44% of people would rather talk to a chat bot than to a human!

In this post we provide a sample solution, called QnABot (pronounced “Q and A Bot”). The QnABot uses Amazon Lex and Amazon Alexa to provide a conversational interface for your “Questions and Answers.” This allows your users to ask their questions and get quick and relevant answers. QnABot can also ask questions and process the answers from your users.

Amazon Lex lets you integrate both voice and text chat access into your existing applications. Amazon Alexa allows you to offer a hands-free voice interface to your users in their homes or workplaces using Amazon Echo or any Alexa-Voice-Service-enabled device. QnABot offers the best of both worlds.

QnABot uses the Amazon Elasticsearch Service (Amazon ES) and optionally Amazon Kendra to make your questions and answers searchable. When a user asks a question, the Amazon ES powerful full-text search engine or Amazon Kendra’s machine learning natural language search engine is used behind the scenes to find the answer that is the best match for that question.

In the sections that follow we’ll show you how to do the following:

  • Deploy QnABot to your AWS account. This blog assumes that you are already an AWS customer. If you want to open an account, choose the Create an AWS Account button on the AWS home page.
  • Populate the QnABot with your questions and answers using the Content Designer UI.
  • Ask questions using voice or chat with the Web Client UI.
  • Ask questions hands-free using the latest Amazon Echo devices.
  • Enrich your answers with images, rich text, and SSML.
  • Support follow-up questions.
  • Support variables and conditional content in your answers.
  • Extend QnABot to integrate with other services and deliver dynamic answers.
  • Get QnABot to ask the questions and have your users provide the answers.
  • Configure rules so QnABot automatically moves on to the next question in a chain or tree of questions.
  • Test, tune, and troubleshoot QnABot content to minimize the chances of getting wrong answers.
  • Modify QnABot configuration settings.
  • Monitor QnABot Usage and User Feedback.
  • Integrate QnABot with Amazon Kendra to find answers from FAQs and unstructured documents.
  • Integrate QnABot with Amazon Connect to provide automation for your call center.

We’ll also take a look under the hood to show you how QnABot works, and give you some ideas for how you can enhance it to suit your needs.

Contents

Click here to open the AWS console and follow along.

Deploying QnABot

Press the Launch Stack button for the Region in which you will use your chatbot:

Northern Virginia
Oregon
Ireland
Sydney
London
Frankfurt
Singapore
Tokyo
Canada Central**

Note: The source code is available in our GitHub repository. Follow the directions in the README to deploy QnABot to additional AWS regions supported by Amazon Lex – see Region Table. 

Open the AWS CloudFormation console, and on the Parameters page, enter a valid Email and Username for the QnABot Content Designer admin user.

** Set LexBotVersion to ‘LexV2 Only‘ when deploying in an AWS region where LexV1 is not supported (e.g. Canada Central).

Choose Next twice to display the Review page.

Select the acknowledgement checkboxes, and choose Create stack to deploy QnABot.

The master CloudFormation stack uses nested stacks to create the following resources in your AWS account:

When the deployment is complete (after about 30 minutes), the master stack Output tab shows the following:

  • ContentDesignerURL: URL to launch the Content Designer UI.
  • ClientURL: URL to launch the user client webpage.
  • DashboardUrl: URL to launch the CloudWatch dashboard for monitoring.
  • FeedbackSNSTopic: Topic name to enable feedback notifications.
  • LexV1 and LexV2 bot information: Useful when configuring integration with contact centers, web clients, etc.

You will receive an email at the email address you provided with the subject “QnABot Signup Verification Code.” This email contains a generated temporary password that you can use to log in and create your own password. Your new password must have a length of at least 8 characters, and contain upper-case and lower-case characters, plus numbers and special characters.

Creating initial content in QnABot

You need to load some question and answer data using the Content Designer, before turning QnABot over to your users. Your data is stored in Amazon ES behind the scenes. This way, the data can be searched later when users ask questions using either an Amazon Lex client UI or an Alexa hands-free device. The steps that follow show you how to load sample questions used to illustrate the features of the QnABot. You can easily substitute your own content later.

  1. In the CloudFormation console, launch the Content Designer webpage using the ContentDesignerURL link from the Outputs tab of the master CloudFormation stack.
  2. Log in with the administrator username you provided when you launched the stack (default: ‘Admin’), and your new password.
  3. Choose Add.
  4. Enter the id: QnaBot.001
    NOTE:     Use a naming convention to identify your items within categories.
  5. Enter the question: What is Q and A Bot
  6. Enter the answer: The Q and A Bot uses Amazon Lex and Alexa to provide a natural language interface for your FAQ knowledge base, so your users can just ask a question and get a quick and relevant answer.
  7. Choose the CREATE button (bottom right of the card).
  8. Repeat steps 3-7, entering the items from the table below.
    Alternatively, to avoid the copy/paste process, you can import the items directly from a file. Choose Import from the top left tools menu ( ☰ ), then choose Examples/Extensions, find the package called blog-samples, and choose LOAD.
  9. When the import is complete, choose Edit from the top left tools menu ( ☰ ), and then choose LEX REBUILD from the top right edit card menu ( ⋮ ). NOTE: We will describe the purpose of the LEX REBUILD later in this post.
Id Question Answer
QnABot.002 How do I use Q and A bot Create and administer your questions and answers using the Q and A Bot Content Designer UI. End users ask questions using the Amazon Lex web UI that supports voice or chat, or using Alexa devices for hands free voice interaction.
Admin.001 How do I modify Q and A Bot content Use the Content Designer Question and Test tools to find your existing documents and edit them directly in the console. You can also export existing documents as a JSON file, make changes to the file, and re-import.
Admin.002 Can I back up Q and A Bot content Yes. Use the Content Designer to export your content as a JSON file. Maintain this file in your version control system or in an S3 bucket. Use the Designer UI Import feature to restore content from the JSON file.
Admin.003 Can I import Q and A Bot content from a file Yes, the Content Designer has an import function that lets you load items from a formatted JSON file. You can create JSON files using the Export feature, or you can write your own tools to create JSON files from existing content such as a website FAQ page.
Admin.004 How do I troubleshoot and fix problems with Q and A Bot. Use the Content Designer test tool to test a question, and check what items are returned, ranked in order of score. If the desired item does not have the highest score, then add the question to the item and run the test again. The desired item should now have the highest score. Take care not to create items with duplicate questions, to avoid unpredictable responses.
Admin.005 How can I find specific Q and A items in the Designer UI Use the Filter feature in the Questions tab to filter the items list based on the ID field. Or use the Test tab to list all the items that match a question.
Media.001 How can I include pictures in Q and A Bot answers Add an image attachment to the item using the Content Designer.

Getting answers using a Lex Web Client UI

You can launch QnABot from a Chrome, Firefox, or Microsoft Edge browser on your PC, Mac, Chromebook, or Android tablet.

  1. On the CloudFormation console, select the main QnABot stack, choose Output, and then choose the link to the ClientURL. Alternatively, launch the client by choosing QnABot Client from the Content Designer tools menu ( ☰ ).
  2. When your browser requests access to the microphone on behalf of the web application, allow it. You’ll see the QnABot chat window:

    You can interact with QnABot using either text chat or voice.
  3. Try it! Choose the microphone icon (bottom right) and say, “What is Q and A Bot?”
    The bot will respond with the answer you previously entered for this question.

Getting answers using Alexa

QnABot also works with Alexa, allowing your users to get answers from your content via any Alexa enabled device, including Amazon FireTV, and any of the Amazon Echo family of devices.

To enable Alexa, first create an Alexa skill for QnABot using the Amazon Developer Console. QnABot can’t automatically create the Alexa skill at this time, so we’ve provided instructions. Log in to the QnABot Content Designer (as explained earlier), and choose Alexa from the tools menu ( ☰ ):

Follow the displayed instructions, step by step, to create an Alexa skill in your Amazon account. It will take you just a few minutes. You can test your new skill in the Amazon Developer Console, even if you don’t have an Alexa enabled device handy.

If you want to publish your QnA skill to the Alexa skills store so other users can access it, see Submitting an Alexa Skill for Certification. Unpublished skills are accessible only to Alexa devices registered to your Amazon account, while published skills are available to anyone.

Adding images to your answers

You can easily augment your answers with image attachments that can be displayed on a user’s Lex Web Client UI, Amazon Alexa smartphone app, or Amazon Echo Show device touch screen. Use images to display maps, diagrams, or photographs to depict places and products relevant to the question.

  1. Log in to the Content Designer, and choose Add
  2. Enter ID: Alexa.001
  3. Enter question: What is an Amazon Echo Show
  4. Enter answer: Echo Show brings you everything you love about Alexa, and now she can show you things. She is the perfect companion for Q and A Bot.
  5. Choose Advanced.
  6. Enter Response card:
    1. Card Title: Echo Show
    2. Card ImageUrl: https://images-na.ssl-images-amazon.com/images/I/61OddH8ddDL._SL1000_.jpg
  7. Choose CREATE to save the new item.
  8. Use the Web UI to ask: “What is an Echo Show?”
    You’ll see the photograph displayed in the web UI chat.
  9. Or, use an Amazon Echo or Echo Dot to say: “Ask Q and A, What is an Echo Show?” The card shown in the Alexa smartphone app shows the photo attachment.
  10. Or, best yet, use an Amazon Echo Show to say: “Ask Q and A, What is an Echo Show?”
    The photo attachment is displayed on the Echo Show’s touch screen.

Use Amazon S3 or a photo sharing service to host your images (see hosting images).

Displaying rich text answers on the web UI

QnABot supports Markdown, allowing you to create beautiful rich text versions of your answers for displaying on the Web UI client, or on Slack. To use this feature, populate the ‘Alternate Markdown answer’ field in Content Designer.

  1. In Content Designer, edit item QnABot001 (“What is Q and A Bot”). Open the Advanced section and enter the following text in the Markdown Answer field:
    # QnaBot
    The Q and A Bot uses [Amazon Lex](https://aws.amazon.com/lex) and [Alexa](https://developer.amazon.com/alexa) to provide a natural language interface for your FAQ knowledge base.
    Now your users can just ask a *question* and get a quick and relevant *answer*.
  2. Choose UPDATE to save the modification:
  3. Use the Web UI to ask: “What is Q and A bot?”.
    You will see that the answer now displays the heading, links, and emphasis specified in your Markdown text.
  4. QnABot also supports inline HTML in the Markdown field. This is very powerful, and allows you to do cool things, like including video clips in your answers. Let’s try it – choose ADD to create a new item:
    1. Enter ID: FireTV.001
    2. Enter question: What is Amazon Fire TV?
    3. Enter answer: Fire TV brings all the live TV and streaming content you love, and Alexa, onto the big screen. Use Alexa on the Fire TV to bring QnABot into your living room!
    4. Enter Markdown answer: 
      **Fire TV** brings all the live TV and streaming content you love, and Alexa, onto the big screen. Use Alexa on the Fire TV to bring QnABot into your living room!
<iframe src="https://www.youtube.com/embed/OE4MrFx2XCs"></iframe>
    5. Choose CREATE to save the item
    6. Use the Web UI to ask: “What is Amazon Fire TV?”.

Markdown is supported by our chatbot web UI.

Using SSML to control speech synthesis

The latest version of QnABot supports SSML, giving you additional control over the speech generation for your response. To use this feature, populate the ‘SSML answer’ field in Content Designer.

  1. In Content Designer, edit item QnABot001 (“What is Q and A Bot”). Open the Advanced section and enter the following text in the SSML Answer field: 
    <speak>QnABot is <emphasis level="strong">great</emphasis>. But I want to tell you a secret. <amazon:effect name="whispered">I am not a real human.</amazon:effect>. Can you believe it? </speak>

    Choose UPDATE to save the modification:

  2. Use the Web UI to ask, using voice: “What is Q and A bot?”, and listen to the whispered response.

Using SSML answers gives you control over voice responses for both Lex and Alexa.

When you are using the web UI, you can use both Markdown and SSML to get QnABot to say one thing (SSML) while displaying another (Markdown). Use this feature to deliver short punchy verbal answers, while taking advantage of the web UI to display rich, illustrated answers.

Using Topics to support follow-up questions

QnABot remembers the topic from the last question you asked, allowing you to ask follow-up questions, for example: “How much does it cost?” The correct answer depends on the context set by the previous question. To use this feature, you assign a value to the Topic field in Content Designer.

  1. In Content Designer, edit item Alexa.001 (“What is an Amazon Echo Show”), and enter “EchoShow” as the Topic in the Advanced section. Choose UPDATE (bottom right) to save the item.
  2. Edit item QnABot.001 (“What is Q and A bot”), and enter “QnABot” as the Topic. Choose UPDATE to save the item.
  3. Choose ADD to create a new item for our first follow-up question:
    • Enter ID: Alexa.Cost
    • Enter question: How much does it cost?
    • Enter answer: For latest prices on the Echo Show, see the Amazon retail site or shopping app.
    • Enter topic: EchoShow
    • Choose CREATE to save the item
  4. Choose ADD to create a new item for our next follow-up question. Enter the following values:
    • Enter ID: QnABot.Cost
    • Enter question: How much does it cost?
    • Enter answer: Q and A Bot is priceless
    • Enter topic: QnABot
    • Choose CREATE to save the item
  5. Use the Web UI to ask the following questions and observe the context appropriate answers:
    1. “What is an Echo Show?”
      • The answer to this question now sets the conversation topic to ‘EchoShow’.
    2. “How much does it cost?”
      • The topic disambiguates this question, so it responds with the answer for the Echo Show.
    3. “What is the Q and A bot?”
      • This question changes the Topic to ‘QnABot’.
    4. “How much does it cost?”
      • The new topic allows the QnABot to respond with the correct answer.

Displaying buttons on the web UI

Add buttons to your answers to help guide your user, by suggesting what they might want to do next. You define and attach buttons to response cards. Let’s try it:

  1. In Content Designer, edit item Alexa.001 (“What is an Amazon Echo Show”)
  2. Find Lex Buttons under Response card in the Advanced section
  3. Enter Display Text: QnABot
  4. Enter Button Value: What is Q and A bot?
  5. Choose ADD LEX BUTTON to add another button
  6. Enter Display Text: FireTV
  7. Enter Button Value: What is Amazon Fire TV?
  8. Choose UPDATE to save the item with your new buttons
  9. Use the Web UI to ask: “What is an Echo Show?”
  10. Choose one of the new buttons to automatically send the next question to QnABot:

Adding style to QnABot

As you define your content, be sure to make your answers light and engaging. Try to adapt a consistent style in your answers. Use images to augment verbal answers. Add flourish to make your bot friendly and stylish!

For example, teach it how to respond to chit-chat like ‘Hello,’ Bye-bye,’ ‘Thanks’ and more.

This is easy to try:

  1. Log in to the Content Designer, and choose Add.
  2. Enter ID: BotStyle.001
  3. Enter question: Hello
  4. Enter answer: Greetings friendly human! Ask me a question. Try to stump me.
  5. Save the new item.
  6. Use the Web UI, or any Alexa device to say “Hello” to your bot, and listen to it respond.

You should also use this technique to teach QnABot to respond with some brief instructions when your users say “Help.”

Using variables and conditional content with Handlebars

QnABot now lets you use Handlebars templates in your answers, including the Markdown and SSML fields, so you can include variable substitution and conditional elements. Let’s try a simple example to illustrate the concept:

  1. Log in to the Content Designer, and choose Add.
  2. Enter ID: Handlebars.001
  3. Enter question: What is my interaction count?
  4. Enter answer: So far, you have interacted with me {{UserInfo.InteractionCount}} times.
  5. Save the new item.
  6. Use the Web UI, or any Alexa device to say “What is my interaction count?” to your bot, and listen to it respond.
  7. Ask a few more questions, and then ask “What is my interaction count?” again. Notice that the value has increased.
  8. In Content designer, edit item Handlebars.001
  9. Modify answer to:

    So far, you have interacted with me {{UserInfo.InteractionCount}} times.
    {{#ifCond UserInfo.TimeSinceLastInteraction '>' 60}}
    It's over a minute since I heard from you last.. I almost fell asleep!
    {{else}}
    Keep those questions coming fast.. It's been {{UserInfo.TimeSinceLastInteraction}} seconds since your last interaction.
    {{/ifCond}}

  10. Use the Web UI, or Alexa, to interact with the bot again. Wait over a minute between interactions and observe the conditional answer in action.

Use the Chatbot Web UI integrated Cognito log in feature to authenticate your QnABot users. When users are authenticated, the chatbot UI attaches a signed token as a session attribute. QnABot uses the token to make additional user attributes available, including fields such as Given Name, Family Name, and Email address.

There’s a lot more that you can do with handlebars, such as randomly selecting content from a list, setting and accessing session attributes, and generating S3 presigned URLs. For more information see Handlebars_README.md in the GitHub repository.

Extending QnABot with Lambda hook functions

Content Designer gives you the ability to dynamically generate answers by letting you specify your own Lambda ‘hook’ function for any item. When you specify the name, or ARN, of a Lambda function in the Lambda Hook field for an item, QnABot will call your function any time that item is matched to a user’s question. Your Lambda function can run code to integrate with other services, perform actions, and generate dynamic answers.

QnABot comes with a simple Lamdba Hook function example that you can explore:

  1. Log in to the Content Designer, and choose Import from the tools menu ( ☰ ).
  2. Open Examples/Extensions, and choose LOAD from the ‘GreetingHook’ example.
  3. When the import job has completed, return to the edit page, and examine the item “GreetingHookExample.” Note that the Lambda Hook field is populated with a Lambda function name.
  4. Use the Web UI to say “What are lambda hooks?”. Note that the answer is prepended with a dynamic greeting based on the current time of day – in this case ‘good afternoon’:
  5. Inspect the example function (ExampleJSLambdahook) using the AWS Lambda console.

Choose Lambda Hooks from the Content Designer tools menu ( ☰) to display additional information to help you create your own Lambda hook functions.

See Extensions README for more information on how you can package lambda hooks in your own copy of the QnABot GitHub repository.

For more information on creating and using Lambda Hooks with QnABot, see Lambda Hook README.

Keyword filters and custom “Don’t Know” answers

Keyword filters

The keyword filter feature helps QnABot to be more accurate when answering questions via Amazon Elasticsearch, and to admit more readily when it doesn’t know the answer. (Keyword filters do not apply when Amazon Kendra is used to find answers – Amazon Kendra integration is discussed in a later section.)

The keyword filter feature works by using Amazon Comprehend to determine the ‘part of speech’ that applies to each word you say to QnABot. By default, nouns (including proper nouns), verbs, and interjections are used as ‘keywords’. Any answer returned by QnABot must have questions that match these keywords, using the following (default) rule:

  • if there are 1 or 2 keywords, then all keywords must match.
  • if there are 3 or more keywords, then 75% of the keywords must match.

If QnABot can’t find any answers that match these keyword filter rules, then it will admit that it doesn’t know the answer rather than guessing an answer that doesn’t match the keywords. QnABot logs every question that it can’t answer so you can see them in the Kibana Dashboard which we’ll show you a little later.

The keyword filters feature is enabled by default, but if it causes problems for you, you can customize its settings, or disable it altogether – see Modifying Configuration Settings.

Custom “Don’t Know” answers

When QnABot can’t find an answer, by default you’ll see or hear the response, “ You stumped me! Sadly I don’t know how to answer your question“. You can easily customize this answer by creating a new item in Content Designer, called the ‘no_hits’ item. Let’s try it. In Content Designer, choose ADD to create a new item:
  1. Enter ID: CustomNoMatches
  2. Enter question: no_hits
  3. Enter answer: Terribly sorry, but I don’t know that one. Ask me another.
  4. Optionally enter provide Markdown and SSML alternatives for your answer, as described earlier.
  5. Choose CREATE to save the item.
  6. Use the Web UI to ask: “What are Echo Buds?”
  7. For bonus points, teach QnABot to answer the question about the Echo Buds, so it can be smarter next time!

Tuning, testing, and troubleshooting

Tuning answers using the Content Designer

By default, QnABot attempts to match a user’s question to the list of questions and answers stored in Amazon Elasticsearch service by the Content Designer. QnABot can also use Amazon Kendra, a machine learning natural language search engine, to find answers. Amazon Kendra integration is discussed in a later section – see “Turbocharging QnABot with Amazon Kendra”.

When using Amazon Elasticsearch, QnABot uses full text search to find the item that is the best match for the question asked. Words that are used infrequently score higher than words that are used often, so sentence constructs such as prepositions have lower weighting than unique keywords. The closer the alignment between a question associated with an item and a question asked by the user, the greater the probability that QnABot will choose that item as the most relevant answer.

QnABot tries to find the best answer to questions by applying the keyword filters discussed above and also by matching the words used in the user’s question to the words used in the question fields of the stored answers, giving preference when the same words are used in the same order.

You might find that users ask questions in ways that you haven’t anticipated, resulting in unexpected answers being returned by QnABot. When this happens, use the Content Designer to troubleshoot and fix the problem.

To illustrate an example troubleshooting / tuning scenario, let’s use the item we entered in the previous section – Admin.001 “How do I modify Q and A Bot content”:

  1. Use the Lex Web UI (voice or text chat) to ask the question in a different way: How can I edit items?
  2. Ideally you want the answer for item Admin.001, but in this case, since the question is phrased very differently than the question associated with this item, you don’t get the desired answer.
  3. Log in to the Content Designer, and choose TEST
  4. Enter the same question you asked, “How can I edit items”, into the question field, and choose SEARCH. There are no results, because none of the questions pass the keyword filter.
  5. In the QUESTIONS tab, find and choose Admin.001. This is our preferred answer.
  6. Let’s tune this item, so that next time you ask the same question this item will have the top score. Choose the item to expand it, choose the edit tool (right), and then ADD QUESTION:
  7. Enter the new question: How can I edit items, and choose the UPDATE button (bottom right of card).
  8. If you have previously enabled Kendra FAQ integration:
    • Select the menu (⋮) from the top right in Content Designer.
    • Choose SYNC KENDRA FAQ and wait for it to complete – it may take a few minutes.
  9. In the TEST tab try the same question again.
  10. Success! This time Admin.001 is a match, and has the highest score.
    Try asking the question again in the Lex Web UI. This time you’ll get the desired answer.

See the QnABot Tuning Accuracy Guide for additional detail and tuning tips.

Testing all your questions

QnABot helps you to quickly test all your questions. Let’s try it:

  1. Log in to the Content Designer, and choose TEST ALL.
  2. Use the default Filename, or enter your own.
  3. If you want to test only a subset of questions, you can optionally filter by qid prefix. Leave this field blank to test all the questions.
  4. Choose the TEST ALL button, and wait for the tests to complete.
  5. Choose the view results icon () on the far right to view the test results.

Behind the scenes, a test function sends every question for every item to QnABot via Amazon Lex, and checks that QnABot matched the question to the expected item. Any incorrect matches are highlighted in red. Test results can be viewed in the browser, or downloaded to your computer as a CSV file.

Tuning the Bot’s Automatic Speech Recognition

When you ask QnABot a question, it’s processed and transcribed by either Amazon Lex or Alexa using an Automatic Speech Recognition (ASR) engine. QnABot initially trains the ASR to match a wide variety of possible questions and statements, so that our Lex bot and Alexa skill will accept just about any question a user might ask. (You can see the default training questions listed in the file default-utterances.js.)

In earlier versions of QnABot you might have found that sometimes you wanted to say things to QnABot that it didn’t understand and would ask you to repeat. In a previous release this problem went away! QnABot now supports the new AMAZON.FallbackIntent in both Lex and Alexa, which allows it to process anything you might say without needing to retrain and rebuild the Lex bot or Alexa skill.

Occasionally you might notice that the transcription shown in the web client or the Alexa app isn’t accurate. This sometimes happens with unusual words that can be confused for other more common words or phrases. You have a couple of options for dealing with this. Either:

  • Use Content Designer to add additional question variants that match the actual transcription shown in the web client or in the Alexa app; this allows QnABot to anticipate the transcription accuracy problem, and respond anyway.
  • Or retrain the Lex and Alexa ASR with examples to influence the transcription to more closely match what you want – see below.

Retrain Amazon Lex

QnABot can automatically generate additional ASR training data for Lex using questions from all the items you have added.

Log in to the Content Designer. Choose LEX REBUILD from the top right edit card menu ( ⋮ ). Wait for the rebuild to complete.

         

The latest version of QnABot automatically generates LexV2 ASR training data in multiple languages using Amazon Translate, for each LexV2 locale specified during installation. Add language specific versions of your questions into Content Designer to fine tune speech recognition accuracy in each language.

Retrain Alexa

QnABot can generate additional ASR training data for Alexa using questions from all the items you have added.

  • Log in to the Content Designer.
  • Choose ALEXA UPDATE from the top right edit card menu ( ⋮ ).
  • Choose COPY SCHEMA to copy the updated Alexa skill schema.
  • Log in to the Alexa Developer Console, open your QnABot skill, and use the JSON Editor to paste the new schema, replacing the existing one.
  • Save and then Build the updated model.

Monitoring QnABot usage and user feedback

QnABot logs what users are saying to your bot. Behind the scenes, we use Amazon Kinesis Data Firehose to store logged utterances to a new index in the Amazon Elasticsearch service.

You can also allow your users to provide feedback on QnABot’s answers. To enable the feedback feature:

  1. Choose Import from the top left tools menu ( ☰ )
  2. Open Examples/Extensions, and choose the LOAD button for the QnAUtility demo.
  3. Choose Edit from the top left tools menu ( ☰ ), and examine the newly imported items, Feedback.001 and Feedback.002; observe the list of default expressions that the user can input to invoke feedback. (The example QnAUtility demo package also loads items Help, CustomNoMatches, CustomNoVerifiedIdentity, .)

Now that you have enabled the feedback feature, try it:

  1. Use the Web UI to ask a question, such as: “What happens if I ask an unanticipated question?”. Since we have not entered a suitable answer for this question, QnABot responds with the newly imported  CustomNoMatches response indicating that it doesn’t know the answer.
  2. In the Web UI, say or type “Thumbs down”, or just click the thumbs down icon ()beside the answer.

QnABot publishes “Thumbs down” feedback messages to the Amazon Simple Notification Service (SNS) topic identified by the FeedbackSNSTopic on the Outputs tab of the master CloudFormation stack. See Subscribing to an Amazon SNS topic to learn how to subscribe to the SNS topic, and receive a message from QnABot each time a user provides feedback.

Visualize the usage logs and feedback using the Kibana dashboard. Note that it can take up to 5 minutes for new utterances and user feedback to become visible in the dashboard.

  1. Choose Kibana Dashboard from the top left tools menu ( ☰ ). Kibana opens in a new browser tab. Choose the QnABot Dashboard to visualize usage history and sentiment, all logged utterances, no hits utterances, positive user feedback, and negative user feedback.
  2. Use Kibana to change the time span, customize and build your own visualizations, or to run your own queries.

Using CloudWatch to monitor and troubleshoot AWS resources

QnABot metrics and logs are available using an Amazon CloudWatch dashboard.

  1. Launch the dashboard using the DashboardUrl on the Outputs tab of the master CloudFormation stack.
  2. When troubleshooting QnABot responses to your questions, trace the request and response using the logs created by the Fulfilment Lambda function.
    1. Choose the menu tool in the upper right of the Fulfilment Lambda widget, choose View logs, and choose the AWSLambda function.

    2. Inspect the log messages. Each interaction with QnABot is delimited by START and END messages. Between these messages you’ll be able to find insights into how QnABot processes the question.

Exporting and importing answers

The QnABot Content Designer allows you to export and import your content using JSON files.

The latest version of QnABot also supports importing questions and answers from Excel workbooks – see Import from Excel for more information.

Use the export feature to create backup versions of your content that you can use to restore if you accidentally delete items or need to go back to a previous version. You can also use exported JSON files to load content into another instance of your bot to help with testing or blue/green deployments.

Or, you might want to automatically create JSON content files using scripts which scrape and reformat content using existing sources like FAQ web pages or documents.

Try it! Let’s export all the items that are in the QnABot category (items whose ID starts with “QnABot”).

  1. Log in to the Content Designer, choose the tools menu ( ☰ ) and Export
  2. Type ‘QnABot’ in the optional filter field, and choose EXPORT to generate a JSON file containing the filtered items. When the export has completed, choose the download tool (bottom right) to download the exported file:
  3. Open the exported file in a text editor and inspect the JSON structure.
  4. Add a new item to the qna list, as shown in the following example, and save the file. 
    {
        "qid": "QnABot.003",
        "q": ["What can Q and A bot do"],
        "a": "You can integrate it with your website to provide quick and easy access to frequently asked questions. Use it with Alexa to provide hands free answers in the kitchen, in the factory or in the car. Since it can display images too, use it to provide illustrations and photographs to enrich your answers.",
        "r": {
            "title": "",
            "imageUrl": ""
        }
}
  5. In the Content Designer, choose Import/Export, and From File. Import your modified JSON file from your local computer. NOTE: Importing items with the same ID as an existing item will overwrite the existing item with the definition contained in the JSON file.
  6. In the Content Designer, enter QnABot in the filter field, and inspect the newly imported item, QnABot.003.

You can use the new export/import command line interface (available in v5.2.0 and later) to programatically backup and restore content – see README.

Modifying configuration settings

QnABot uses AWS Systems Manager Parameter Store to hold default and custom configuration settings. You can now view and edit these settings using the new Settings menu in the Content Designer.
  • Log in to the Content Designer, choose the tools menu ( ☰ ) and choose Settings
  • Change the value of the setting ES_USE_KEYWORD_FILTERS from true to false
  • Scroll to the bottom and choose Save
Congratulations, you have just disabled the new keyword filters feature that we discussed earlier! For proof, let’s repeat an exercise we did earlier:
  1. Use the Web UI to ask a question that the bot can’t answer, such as: “What happens if I ask an unanticipated question?”
  2. Observe that now, instead admitting it doesn’t know, QnABot simply returns the best match, which in this case is clearly not useful. Give it a thumbs down!
Enable the keyword filters feature again by setting ES_USE_KEYWORD_FILTERS back to true or by choosing RESET TO DEFAULTS.
Test it again to make sure you successfully re-enabled the feature. QnABot admits that it doesn’t know the answer.
You can also customize how the keyword filters feature works by changing:
  • ES_KEYWORD_SYNTAX_TYPES:  A list of tokens representing parts of speech identified by Amazon Comprehend.
  • ES_MINIMUM_SHOULD_MATCH: A query rule used to determine how many keywords must match an item question in a valid answer.

Explore the available configuration settings, and override the defaults to configure QnABot customize keyword filtering, answer field scoring, messages, redaction from logs and metrics (ENABLE_REDACTING and REDACTING_REGEX), and more. In the latest release you can enable the new debug mode (ENABLE_DEBUG_RESPONSES), enable fuzzy matching (ES_USE_FUZZY_MATCH), and experiment with score boosting for exact phrase matches (ES_PHRASE_BOOST).

In the latest release you can now also add new custom settings to use in your Lambda Hook functions and Handlebars.

Refer to the QnABot Settings README for more information on all the settings available in the latest version of QnABot.

Custom settings will not be replaced when you upgrade QnABot.

Turbocharging QnABot with Amazon Kendra

Now you can easily integrate QnABot with the new Amazon Kendra service, a powerful enterprise search service that’s powered by machine learning. There are two ways to take advantage of Amazon Kendra’s natural language processing model to enhance QnABot’s ability to understand human questions:

  1. Use Amazon Kendra’s FAQ queries to match users’ questions to the answers in the QnABot knowledge base. Kendra’s machine learning models can handle many variations in how users phrase their questions, and this can reduce the amount of tuning needed for QnABot to find the right answer from your knowledge base.
  2. Use Amazon Kendra’s document index as a fallback source of answers when a question/answer is not found in QnABot’s knowledge base.

Review Amazon Kendra Pricing and then follow the Amazon Kendra Getting Started documentation to deploy your first Amazon Kendra index.

Using Kendra FAQ for question matching

Configure QnABot to use your new Amazon Kendra index to answer questions from the items you’ve populated in Content Designer:

  1. Update the QnABot setting KENDRA_FAQ_INDEX to specify the Amazon Kendra index to use. Copy/paste your Index ID from the Amazon Kendra console.
    (If you previously provided a value for the parameter DefaultKendraIndexId when you installed or updated QnABot, then KENDRA_FAQ_INDEX will be pre-configured.)
  2. Replicate all items from Content Designer to the Kendra index:
    • Select the menu (⋮) from the top right in Content Designer.
    • Choose SYNC KENDRA FAQ and wait for it to complete – it may take a few minutes.

QnABot will now try to use Kendra FAQ queries to find matches to users’ questions. Use the setting ALT_SEARCH_KENDRA_FAQ_CONFIDENCE_SCORE to adjust the confidence threshold for Kendra FAQ answers used by QnABot.

If Kendra FAQ cannot not find an answer that meets the confidence threshold, QnABot will revert by default to using an Elasticsearch query. The combination of Kendra FAQ and Elasticsearch gives you the best of both worlds.

Using Kendra search as a fallback source of answers

Add one or more data sources to your Amazon Kendra index, and configure QnABot to query your index any time it gets a question it doesn’t know how to answer:

  1. Update the QnABot setting ALT_SEARCH_KENDRA_INDEXES to specify one or more Amazon Kendra indexes to use for fallback searches. The value of ALT_SEARCH_KENDRA_INDEXES should be either a single index id, or an array of quoted index ids, for example:
    857710ab-example-do-not-copy OR ["857710ab-example1-do-not-copy","857710ab-example2-do-not-copy"]
    (If you previously provided a value for the parameter DefaultKendraIndexId when you installed or updated QnABot, then ALT_SEARCH_KENDRA_INDEXES will be pre-configured.)

QnaBot is now enabled to pass questions along to Amazon Kendra when it can’t provide an answer itself. Try it, by asking a new question that can only be answered from your new Amazon Kendra index.

You might get a short suggested answer, like this:

Or you might get highlighted search results, like this:

Try it using voice. QnaBot generates a more compact voice response by pruning the first search result to contain only the most relevant sentences.

QnABot can generate S3 presigned URLs, so your documents in S3 don’t need to be public for the Source Links to work. To enable presigned URLS:

  • Set ALT_SEARCH_KENDRA_S3_SIGNED_URLS true
  • Use an S3 bucket with a name that starts with QNA* or qna* to store the documents in your Amazon Kendra index

Use the setting ALT_SEARCH_KENDRA_FALLBACK_CONFIDENCE_SCORE to adjust the confidence threshold for Kendra search results used by QnABot.

Web page indexer

QnABot can now answer questions based on the content of web pages. Let’s try it:

  1. In Content Designer, choose the tools menu ( ☰ ) and then Settings. Change
    1. ENABLE_WEB_INDEXER: true
    2. KENDRA_INDEXER_URLS:  https://aws.amazon.com/lex/faqs/
    3. KENDRA_WEB_PAGE_INDEX: Existing Amazon Kendra index ID
    4. KENDRA_INDEXER_SCHEDULER: rate (1 day) 
  2. In Content Designer, choose the tools menu ( ☰ ) and then Kendra Web Page Indexing
    1. Choose START INDEXING if available. (It may be greyed out because the indexer starts automatically when enabled for the first time)
    2. Wait for indexing to complete (it can take several minutes)
  3. Open the QnABot web UI, and ask “What is Lex?” QnABot provides an answer with a link to the Amazon Lex FAQ page.

See README for more information on web page indexing.

More information on QnABot / Kendra integration

Our QnaBot workshop provides additional details and step by step instructions on QnABot/Kendra integration.

Supporting multiple languages

You can configure QnABot to answer a question in the same language used to ask the question (text interaction and Alexa skills), and it doesn’t have to be English. QnABot supports automatic default translation to the user’s language using Amazon Translate.

  • Enable multiple language by setting: ENABLE_MULTI_LANGUAGE_SUPPORT true.
  • In the web UI, ask: Qu’est-ce que q et a bot?  
  • QnABot replies to you in French.

In the latest version, using LexV2, QnABot now supports speech recognition and voice interaction in multiple languages. When you install or update QnABot, specify the languages using the CloudFormation parameter LexV2BotLocaleIds. The default languages are US English, US Spanish, and Canadian French; you can customize the list to use any of the languages supported by Amazon LexV2.

  • In the web UI, set the locale to Canadian French
  • Choose the microphone icon (bottom right) and say in French: Qu’est-ce que q et a bot?
  • QnABot replies to you in French.

Use the ENABLE_DEBUG_RESPONSES setting to see how local language questions are translated to English by QnABot, and use this translation to tune the content as needed to ensure QnABot finds the best answer to a non-English question.

When you need additional control over the translated response, use Handlebars syntax to provide answers for specific languages. For more information please read the companion blog post: Building a multilingual question and answer bot with Amazon Lex.

QnABot supports Amazon Translate custom terminology to provide additional control over the translation of entities and phrases. The README provides more information and explains how to use the new Import Custom Terminology tool in Content Designer.

Configuring QnABot to ask the questions

UPDATE: QnABot v5.2.0 introduces a capability to directly create new custom Amazon Lex bot slottypes, intents, and slots right from the Content Designer UI.  You can use this feature to leverage powerful Lex NLU intent matching and slot filling capabilities with QnABot to not only find the right answers, but also define multi-turn conversations to elicit slot values that you can reuse later for conditional responses, conditional branching, or in custom business logic. See the README for more information, and consider experimenting with this approach as an alternative to the ResponseBot approach outlined below.   

QnABot was designed to answer questions, but now it can also ask questions and process the user’s answers. Use this feature for data collection and validation; to implement surveys, quizzes, personalized recommendations; or triage chatbot applications.

Let’s try it.

  1. Log in to the Content Designer and choose Add
  2. Enter ID: ElicitResponse.001
  3. Enter question: Ask my name
  4. Enter answer: Hello. Can you give me your First Name and Last Name please.
  5. Choose Advanced.
    1. Enter Elicit Response: ResponseBot Hook: QNAName
    2. Enter Elicit Response: Response Session Attribute Namespace: name_of_user
  6. Choose CREATE to save the new item.
  7. Use the Web UI to say: “Ask my name”
  8. Respond by entering your name. Try responding naturally and see if QnABot confirms your name correctly. If not, you can choose NO and try again.

Behind the scenes, QnABot is using Amazon Lex to process your responses. The ResponseBot Hook field specifies the name of an Amazon Lex bot. In this case we specified the name of a bot, QNAName, that was automatically created for us when QnABot was installed. QNAName is a built-in response bot designed to process names (first and last name). It handles a variety of ways the user might state their name, and it will prompt the user to confirm or to try again. If the user confirms by choosing YES, the response bot will return the FirstName and LastName values back to QnABot (as slot values in a ‘fulfilled’ response).

QnABot stores the returned FirstName and LastName values in a session attribute. The name of the session attribute is determined by  the value you provided for Response Session Attribute Namespace (in this case name_of_user) and the slot name(s) returned by the response bot (in this case FirstName and LastName).

The session attribute set by Elicit Response can be used in other items to provide conditional or personalized responses.

  1. Log in to the Content Designer, and choose Add
  2. Enter ID: ElicitResponse.002
  3. Enter question: Ask my age
  4. Enter answer: Hello {{SessionAttributes.name_of_user.FirstName}} – What is your age in years? 
  5. Choose Advanced.
    1. Enter Elicit Response: ResponseBot Hook: QNAAge
    2. Enter Elicit Response: Response Session Attribute Namespace: age_of_user
  6. Choose CREATE to save the new item.
  7. Use the Web UI to say: “Ask my age”

Did you notice that QnABot now greeted you by your first name before asking your age? The handlebars expression, {{SessionAttributes.name_of_user.FirstName}}, was replaced by the value of the session attribute set by your answer to the previous question.

Response Bots

QnABot provides a set of built-in response bots that you can use out of the box:

  • QNAYesNo: returns slot “Yes_No” with value either “Yes” or “No”
  • QNAYesNoExit: returns slot “Yes_No_Exit” with value either “Yes”, “No”, or “Exit”
  • QNADate: returns slot “Date” with value of date (YYYY-MM-DD)
  • QNADayOfWeek: returns slot “DayOfWeek”
  • QNAMonth: returns slot “Month”
  • QNANumber: returns slot “Number”
  • QNAAge: returns slot “Age”
  • QNAPhoneNumber: returns slot “PhoneNumber”
  • QNATime: returns slot “Time” with value of time (hh:mm)
  • QNAEmailAddress: returns slot “EmailAddress”
  • QNAName: returns slots “FirstName” and “LastName”
  • QNAFreeText: returns slots “FreeText” and “Sentiment” (New in 4.0.0 – used to capture free-form notes or comments that can be used in, say, trouble tickets, emails, or for feedback sentiment analysis.). 

You can also add your own Amazon Lex bots and use them as response bots. Response bot names must start with the letters “QNA”. QnABot calls your bot with the user’s response, and captures all the slot names and values returned when your bot sends back a fulfilled message.

QnABot now supports LexV2 response bots. Use LexV2 for all new response bots, so that you can take advantage of future Lex feature enhancements and region expansion.

  • Collect the Bot ID and Alias ID values for your response bot, using the LexV2 console.
  • In content Designer, identify your LexV2 response bot in the Elicit Response: ResponseBot Hook field as: “LexV2::<BOTID>/<ALIASID>/en_US”.

Session attribute values set by Elicit Response are contained in the context object passed to custom Lambda Hook functions. Use Lambda Hook functions to store the user’s responses to a database, to perform lookups, and to implement additional personalization features.

The session attribute set by Elicit Response can also be used in Conditional Chaining rules to determine what item to go to next. Let’s try that in the next section.

Automatically advancing and branching along a tree of questions (New)

Let’s configure QnABot to automatically ask your age after you provide your name.

  1. Log in to the Content Designer and edit item ElicitResponse.001
  2. Choose Advanced.
    1. Enter Document Chaining: Chaining Rule: 'ask my age'
  3. Choose UPDATE to save the modified item.
  4. Use the Web UI to ask: “Ask my name”
    1. Enter and confirm your name.
    2. Enter and confirm your age.

Now QnABot automatically asks you for your age after you confirm your name! Because you specified the next question, ‘ask my age‘, as the Chaining Rule, QnABot automatically found and advanced to the matching item.

Let’s take it a step further by creating a conditional chaining rule that will branch to different items depending on previous answers.

  1. Log in to the Content Designer and add two new items:
    1. ID: ElicitResponse.003, question: “Under 18″, answer: “Under 18 answer“.
    2. ID: ElicitResponse.004, question: “Over 18“, answer: “Over 18 answer“.
  2. Edit item ElicitResponse.002
    1. add Chaining Rule: (SessionAttributes.age_of_user.Age< 18) ? "Under 18" : "Over 18" 
    2. Choose UPDATE to save the modified item.
  3. Use the Web UI to ask: “Ask my name”
    1. Enter and confirm your name.
    2. Enter and confirm your age.

When you confirm your age, now QnaBot automatically branches to one of the two new items you added, depending on your age. The Chaining Rule used here is a JavaScript programming expression used to test the value of the session attribute set by Elicit Response; if it is < 18 then advance to the item matching the question ‘Under 18′, otherwise advance to the item matching the question ‘Over 18′.

Combine expressions with logical operators to test multiple Session Attributes in a single rule, and use nested expressions to implement more than two branches in a Chaining Rule. Use the alternate syntax SessionAttributes('age_of_user.Age') to avoid a processing error if the referenced session attribute does not exist.

You can now also apply chaining rule expressions to all the context variables supported by the handlebars feature including UserInfo fields, Settings fields, and more – see README for a list of available variables.

Identify the next document using its Qid value instead of a question using a string that starts with ‘QID::‘ followed by the Qid value of the document, e.g. a rule that evaluates to “QID::Admin001” will chain to item Admin.001.

You can optionally specify an AWS Lambda function instead of a JavaScript expression when you need to evaluate complex Chaining Rule logic. Your Lambda function is invoked with the full user request context and should evaluate and return the ‘next question’ as a simple string. Alternatively the Lambda function may return an event object where the ‘event.req.question’ key has been updated to specify the next question – by returning an event object, your Chaining Rule Lambda function can modify session attributes, similar to Lambda Hooks. Use Lambda functions to implement Chaining Rules that require complex logic, data lookup, etc. A Chaining Rule Lambda function name must start with the letters “QNA”, and are specified in the Document Chaining:Chaining Rule field as: Lambda::FunctionNameOrARN.

Be careful when writing Chaining Rules. It is easy to accidentally introduce a JavaScript syntax error or to reference an invalid session attribute. If the chaining rule has an error, the QnABot will return the message, “Unfortunately I encountered an error when searching for your answer. Please ask me again later.”

Can you implement a new Answer for seniors who are over 60? To see how, use Content Designer to import the new sample package, ConditionalChainingDemo. Use the Web UI, entering Start to see the first question.

Looking under the hood

Let’s take a quick look at how QnABot works. Here’s a diagram of the main architectural components and how they fit together at a high level.

The following sections explain how all these architectural components work together for different modes of interacting with QnABot. For additional detail, see the source code and READMEs in the GitHub repository, and use the AWS console to explore the configuration of each of the resources.

Amazon Lex web client

Amazon Lex allows conversational interfaces to be integrated into applications like our Lex web client. A Lex bot uses intents to encapsulate the purpose of an interaction, and slots to capture elements of information from the interaction. Since QnABot has a single purpose, to answer a user’s question, it defines just one intent. This intent has a single slot which is trained to capture the text of the question. QnABot also uses the AMAZON.FallBackIntent to ensure that all user input is processed (see the discussion of “Tuning the Bot’s Automatic Speech Recognition” earlier). To learn more about how Amazon Lex bots work, and to understand the concepts of intents, slots, sample values, fulfillment functions, and more, see the Amazon Lex Developer Guide.

The QnABot Lex web client is deployed to an Amazon S3 bucket in your account, and accessed via Amazon API Gateway.

An Amazon API Gateway endpoint provides run time configuration. Using this configuration, the web client connects to Amazon Cognito to obtain temporary AWS credentials, and then connects with the Amazon Lex service.

When you use the Lex web client to ask QnABot a question, for example, “How can I include pictures in Q and A Bot answers?”, the web client interacts with the QnABot Lex bot. The Lex bot then invokes the Bot fulfillment Lambda function in your AWS account with the transcribed question captured as a slot.

The Bot fulfillment Lambda function generates an query containing the transcribed question.

If you have enabled Amazon Kendra FAQ integration with QnABot (see “Turbocharging QnABot with Amazon Kendra”) then QnABot will first attempt to find the answer using a Kendra FAQ query.

An Amazon Elasticsearch query is used to find the answer, if any of the following are true:

  • Amazon Kendra FAQ integration is not enabled (default)
  • Amazon Kendra FAQ integration is enabled, and:
    • The question is a follow-up question using a topic (Kendra does not currently support FAQ queries with topics)
    • The question specifies a specific Qid (starts with ‘QID::’)
    • The Kendra FAQ query did not find an answer, and the setting KENDRA_FAQ_ES_FALLBACK is true (default)

The following example shows the Amazon Elasticsearch (ES) query. The query attempts to find the best match from all the questions and answers you’ve previously provided, filtering items to apply the keyword filters and using Amazon ES relevance scoring to rank the results. Scoring is based on (i) matching the words in the user’s question against the unique set of words used in the stored questions (“quniqueterms”), (ii) matching the phrasing of the user’s question to the text of stored questions (nested field: questions.q), and (iii) matching the topic value assigned to the previous answer (if any) to increase the overall relevance score when topic value (field t) matches.

QnABot supports Elasticsearch fuzzy matching which makes it more tolerant of misspellings and typing errors in the user input. Enable this feature in the Settings page:

  • Log in to the Content Designer, choose the tools menu ( ☰ ) and choose Settings
  • Change the value of the setting ES_USE_FUZZY_MATCH from false to true
  • Scroll to the bottom and choose Save

In previous releases, QnABot also included matches found in the answer field to give greater relevance to items where the answer contains multiple references to the terms used in the user’s question. This is not always desirable, however, since term matches contained in the answer field can make it harder to predict and control the items you want to score highest for any question. QnABot v4.0.0 and later disables this feature by default. You can, of course, turn it on again using the Settings page:

  •  Log in to the Content Designer, choose the tools menu ( ☰ ) and choose Settings
  • Change the value of the setting ES_SCORE_ANSWER_FIELD from false to true
  • Scroll to the bottom and choose Save

The Bot fulfillment Lambda function uses the answer field (or the alternate Markdown or SSML fields if they have been populated) from the item with the highest score to create a response to send back to Lex. If the item also contains an image attachment, a response card is also sent back in the response. The Lex web client responds to the user with either voice or text depending on the mode of operation, and also displays any images attached to the answer.

Alexa-enabled devices

Alexa devices interact with QnABot using an Alexa skill. Like a Lex bot, an Alexa skill also uses intents to encapsulate the purpose of an interaction, and slots to capture elements of information from the interaction. The QnABot Alexa skill mirrors the setup of the Lex bot described above.

The Alexa QnA skill uses the same Bot Fulfillment Lambda function as the Lex bot. When you ask a question, for example, “Alexa, ask Q and A, How can I include pictures in Q and A Bot answers?”, your Alexa device interacts with the skill you created, which in turn invokes the Bot fulfillment Lambda function in your AWS account, passing the transcribed question as a parameter.

The Bot fulfillment Lambda function queries Amazon ES items as described earlier. The Bot fulfillment Lambda function uses the answer field from the item with the highest score to create a response to send back to Alexa. If the item also contains an image attachment, a card is also sent back in the response, causing the image to be displayed in the Alexa smartphone app. If you use an Echo Show or Echo Spot the image will be displayed on the touchscreen, or if you use Alexa on your Amazon FireTV the answers and images will be displayed on your big screen TV.

Content Designer UI

The QnABot Content Designer UI, like the Web Client, is also deployed to an Amazon S3 bucket and accessed via Amazon API Gateway, and it too retrieves configuration from an API Gateway endpoint. The Content Designer website requires the user to sign in with credentials defined in a Cognito user pool.

Using temporary AWS credentials from Cognito, the Content Designer UI interacts with secure API Gateway endpoints backed by the Content Designer Lambda functions. All interactions with Amazon ES and Amazon Lex are handled by these Lambda functions.

Customizing and enhancing QnABot

Fork the QnABot GitHub repository, enhance the code, and send us pull requests so we can incorporate and share your improvements!

Here are a few suggestions for features you might want to implement:

  • Multiple answers: Allow the user to request a different answer by saying “Try again,” or “Next” to instruct QnABot to reply with lower ranked answers. Useful when questions are ambiguous or when there is more than one correct answer.
  • Scrape existing FAQ pages or documents: Write scripts to capture content from existing suitable sources. Automate, or semi-automate the creation of the QnABot JSON or Excel format files for importing.
  • Extend QnABot to access public knowledge base services: Tap into Wikipedia, Evi, WolframAlpha, or other public knowledge servers by extending the Bot fulfillment Lambda function to access additional external information sources.

Using QnABot in an Amazon Connect or Genesys Cloud contact center

Integrate QnABot with Amazon Connect. Lower your support center call wait times by automating data collection and answering frequently asked questions using QnABot within an Amazon Connect contact flow. Or configure QnABot to use Amazon Connect to make outbound calls; your users can use the Web UI or Alexa skill to ask QnABot to call their phone so they can speak to a human.

Use the new Connect integration wizard to try QnABot in your first call center:

  • Log in to the Content Designer, choose the tools menu ( ☰ ) and choose Connect
  • Follow the step by step directions to create a contact center using QnABot to answer caller’s questions.

NOTE: When QnABot is installed in “LexV2 Only” mode the Connect integration wizard creates a sample contact flow which uses LexV2, and which showcases the ability to support voice calls in multiple languages using a single instance of QnABot.

For more information see the Amazon Connect lab in our new QnABot workshop and watch this video.

The latest release of AWS QnABot can also be integrated easily with the Genesys Cloud contact center platform using the new Genesys Cloud integration wizard in Content Designer. Watch this video demo to see it in action.

Using QnABot with SMS text messaging, Slack, and other channels

Allow users to interact using texting by setting up Twilio to provide an SMS channel for the QnABot. See Twilio and Amazon Lex Integration, and try the SMS lab from our QnABot workshop.

You can also use other popular messaging platforms, such as Slack, to interact with QnABot.

Using QnABot as a router to connect to other bots (Preview feature)

QnABot can now be configured to route conversations to other bots, called ‘specialty bots’. A specialty bot can be:

  1. Another instance of QnABot configured to handle a specific set of topics (e.g. HR department bot, IT department bot, etc.)
  2. Another Amazon Lex bot designed to handle specific intents (e.g. schedule an appointment, place an order, etc.)
  3. A third party chat bot that provides a specialty service.

Use a single instance of QnABot as a ‘supervisory bot’ that can route conversations to specialty bots behind the scenes, and provide an integrated user experience on Alexa or on any of the Amazon Lex channels supported by QnABot.

To learn more about how to set up bot routing, see the Bot Routing README.

Deploying QnABot in a VPC (Preview feature)

Does your organization have a security posture that prefers Amazon Elasticsearch domains to be accessible only from within your VPC? In the latest release you now have the option to deploy QnABot into your existing VPC subnets.

To learn more about QnABot VPC deployment, see the VPC Support README.

Quizzes and Guided tours

Did you know that you can also get QnABot to ask multiple choice questions and grade your answers? See this companion blog post to find out how: Create a questionnaire bot with Amazon Lex and Amazon Alexa

As described earlier, you can now use buttons to guide the user through your content on the web UI. You can also implement a guided tour with full text and voice support, using Next and Previous commands to navigate. See Creating virtual guided navigation using a Question and Answer Bot with Amazon Lex and Amazon Alexa

About the web UI

The QnABot uses the chatbot web UI described in the blog post: Deploy a Web UI for Your Chatbot.

You can easily deploy this Chatbot UI separately to integrate QnABot as a component into your own website. The Chatbot UI offers many features, including optional integrated user authentication which you can use to create personalized responses from QnABot.

Upgrading QnABot

Option 1: Install new stack (Recommended)

If you have installed an earlier version of QnABot, you should use the Export feature to create a JSON file containing all your Q and A content. Install this latest version as a new stack (follow above instructions), and use the Import option to load your saved JSON file.

After importing your content, run tests to validate that your questions are answered correctly. You might find that you need to retune some existing questions for the new version.

After you have validated that the new QnABot is answering questions as expected, you can switch users over, and uninstall the old version.

Option 2: Upgrade existing stack

You can use CloudFormation to upgrade your existing QnABot stack. Before doing a production upgrade, be sure to use the Export feature to create a JSON file containing all your Q and A content. Create a test installation of the new version, import your content, and test all your questions. You might find that you need to retune some existing questions.

Upgrade your production QnABot stack only when you are sure that the latest version passes all your tests:
  1. On the CloudFormation console, select the main QnABot stack.
  2. Choose Update.
  3. Choose Replace current template.
  4. Enter Amazon S3 URL: https://solutions-reference.s3.amazonaws.com/qnabot-on-aws/latest/qnabot-on-aws-main.template
  5. Choose Next three time to display the Review page.
  6. Select the acknowledgement checkboxes, and choose Update Stack to upgrade QnABot.
  7. Kendra Fallback users only: If you enabled Kendra Fallback in an earlier release, then after you update to v4.6.0 or later you must remove the custom KendaFallback ‘no_hits’ item. In Content Designer:
    1. Find the item KendraFallback and delete it.
    2. Find the item CustomNoMatches if it exists, and re-enable it by modifying the question “no_hits_original” to “no_hits”. If the CustomNoMatches item does not exist, you can create it as described in the section titled Custom “Don’t Know” answers, or by importing the QnAUtility demo package.

Uninstalling QnABot

When you’re done experimenting, in the CloudFormation console, choose and delete the master QnABot stack. This removes all of the AWS resources associated with the bot. Be sure to first export any QnA items that you want to reuse later.

Summary

This blog shares our sample Question and Answer bot, QnABot. We explain how you can use QnABot to create a natural language interface that works with both text and voice using Amazon Lex via your web browser, an Amazon Connect call center, SMS text, or with any Alexa-enabled device. Now you can try it with your own questions and answers!

To learn more about QnABot, try our new QnABot Workshop.

Please use the comments link to share your experiences with the QnABot – we’d love to hear from you!

New features log

  • July 2022 (v5.2.0) – Introduces Amazon Lex Intent and Slot matching support directly from QnABot Content Designer (more).  Support for using custom domain names for QnABot Designer and Client interfaces (more). AWS QnABot Command Line Interface (CLI) for content export/import (more). New Kendra Redirect feature allows you to retrieve an answer using a targeted Kendra query with optional filters (more). Integration with Canvas LMS (an early example implementation), allowing students to ask QnABot about their grades, syllabus, enrollments, assignments, and announcements (more). For additional information on this release, see CHANGELOG.md on GitHub.
  • December 2021 (v5.1.0) – New Genesys integration wizard in Content Designer makes it easy to add QnABot to Genesys Cloud powered contact centers. Bot routing now supports Lex V2 specialty bots. Session attributes can now be defined in Content Designer, with optional language translation and handlbars support. New client filtering support allows answers to be filtered by matching a session attribute to proconfigured values assigned to items in Content Designer. Enhanced PII log redaction using Amazon Comprehend. New example integration with Canvas Learning Management System (LMS). New support for pre and post processing Lambda hooks configured in Content Designer settings. Tags are now supported for each item in Content Designer allowing tag based reports to be created in Kibana.  
  • September 2021 (v5.0.0) – The AWS QnABot is now available in the AWS Solutions library. The Amazon Connect integration wizard now creates a  sample contact flow supporting multi-lingual Connect/LexV2 integration in all supported regions.
  • August 2021 (v4.7.3) – The QnABot fulfillment Lambda function can now be configured for provisioned concurrency to further improve query response times after periods of inactivity. 
  • July 2021 (v4.7.1) – Amazon Elasticsearch is now updated to v7.10 and encrypted (production) instance types are upgraded to m6g.large.elasticsearch for improved price/performance. The QnABot fulfillment Lambda function has been optimized to reduce query response times and variability, especially after periods of inactivity. LexV2 built-in Elicit Response bots have been added. Custom settings can now be exported and imported from the Content Designer Settings page. 
  • June 2021 (v4.7.0) – QnABot now supports LexV2 with voice interaction in multiple languages. Two installation/update modes are now available (i) LexV1 + LexV2 (default, recommended for most AWS regions), and (ii) LexV2-only (currently recommended for AWS regions where LexV1 is not available). LexV2 locales are specified via a new CloudFormation parameter – the default locales are US English, US Spanish and Canadian French. The QnABot web client now uses LexV2 and supports dynamic bot locale selection from a new title bar menu. Custom LexV2 Elicit Response bots are now supported (the built-in response bots still use LexV1 and are available only when QnABot is installed in LexV1+LexV2 mode). CloudFormation deployment is now available for Canada Central region (LexV2-only mode). Amazon Connect integration in the Canada Central region supports multiple voice languages using LexV2 (multi-language voice support for additional AWS regions will be coming soon). The Content Designer ‘Test All’ feature now uses LexV2. Content Designer’s “Rebuild Lex Bot” feature now rebuilds both LexV2 and LexV1 bots – non-English LexV2 bot locales are automatically generated with sample utterances translated from English questions using Amazon Translate. Content Designer’s Import feature now supports Excel spreadsheets as well as the existing JSON format. QnABot’s Elasticsearch cache is now automatically kept warm to improve query time consistency. Negative feedback (thumbs down) messages can now generate notifications (text, email, etc.) using Amazon SNS. 
  • April 2021 (v4.6.0) – Kendra integration is now fully automated during install or update when the new Default Kendra Index Id parameter is provided. Kendra custom no_hits item required in earlier releases is no longer required to enable Kendra Fallback and should be removed. Configurable confidence thresholds now available for filtering Kendra results. Kibana dashboard now shows additional detail on questions answered via Kendra FAQ and Kendra Fallback. Sstandard markdown is now automatically converted to Slack markdown when using Slack. Kibana dashboard logs and metrics retention period is now configurable during install or update. Lambda runtime upgraded to Node.js 12.x.
  • March 2021 (v4.5.0) – Added CloudFormation deployment for four additional regions (London, Frankfurt, Singapore, Tokyo), upgraded Amazon Elasticsearch instance types to t3.small.elasticsearch (unencrypted) and c5.large.elasticsearch (encrypted), changed default encryption setting to ENCRYPTED for improved compliance and changed default Elasticsearch node count from 2 to 4 for improved performance and fault tolerance for production deployments, new capability to answer questions based on web page content with scheduled web page scraping and indexing with Amazon Kendra,  new capability to reject utterances containing Personal Identifiable Information using Amazon Comprehend, enhanced multiple language support now includes custom terminology for Amazon Translate and can now translate responses from Amazon Kendra and Lambda Hooks,  pre-signed S3 URLs for non-public S3 objects can now be embedded in answers and used for response card image URLs using handlebar syntax, Lambda Hook functions can now be used in items that are concatenated with Document Chaining rules, utterances using common contractions (I’m, you’re, etc.) can now be expanded prior to question matching for better accuracy, Kendra Fallback message prefixes are now configurable in QnABot settings.
  • December 2020 (v4.4.0) – Elasticsearch updated to v7.9, detection for Slack client and Handlebars support for Slack specific markdown answers, support for Alexa re-prompts, new Bot Router feature (preview), new VPC deployment template (preview). 
  • October 2020 (v4.3.0) – Amazon Connect integration wizard in Content Designer, 4-node Elasticsearch domain support for improved fault tolerance, Elicit Response bot support for confirmation responses using phone keypad 1 = yes 2 = no, Security improvements in API Gateway, ID token values removed from session event after validation and redacted from logging, Setting to limit number of Kendra fallback search results, Setting to enable signed URLs for S3 documents in Kendra search results. 
  • August 2020 (v4.2.0) – Amazon Kendra NLP available as optional alternative to Elasticsearch queries for better accuracy and easier tuning, Kendra fallback supports shorter responses when using voice channels, Elasticsearch updated to v7.7, new handlebars ‘getSessionAttr’ helper function, document chaining rule Lambda functions can set session attributes by returning modified event object (like Lambda Hooks), document chaining supports up to 10 uninterrupted chained documents, repeat last answer using REPEAT document included in QNAUtility package, ‘previous’ and ‘navigation’ session attributes are now encapsulated in the session variable ‘qnabotcontext’ to simplify Amazon Connect contact flow design, query based on document Qid using question syntax ‘QID::<qid>’. 
  • July 2020 (v4.1.0) – Encryption at rest installation option, private installation option requires Cognito user authentication for web client access, option to enforce user identity token verification, Amazon Kendra integration supports ‘best answer’ and bolded highlights in markdown responses, sentiment is now detected and made available to use in conditional chaining rules / handlebars / lambda hooks, the new QNAFreeText feature now provides additional ‘Sentiment’ slot value, Kibana dashboard now shows sentiment distribution in the requests histogram and provides more fine grain identification of Amazon Lex client types (Lex Web UI, Amazon Connect, Twilio), ElicitResponse state is now encapsulated in a single session variable ‘qnabotcontext’ to simplify Amazon Connect contact flow design when using ElicitResponse, new session attributes now provided for clients (eg Amazon Connect) to use – qnabot_qid and qnabot_gotanswer.
  • June 2020 (v4.0.0) – Update to Elasticsearch 7.4, improved question matching accuracy and tuning, tolerance for typos and minor spelling errors with fuzzy matching setting, easier troubleshooting when using voice or multi-language support with new debug setting, SSML support when using Amazon Connect, improvements to Amazon Kendra integration, new QNAFreeText feature to capture free-form input when using ElicitResponse, full upgrade support without data loss when upgrading from previous versions.
  • April 2020 (v3.0.3) – Improved concurrency scaling using Lex versions and aliases, extensible Document Chaining rules using Lambda functions, redact sensitive information from QnABot logs and metrics using configurable regular expressions, new example package for using Amazon Connect call-back to transfer QnABot user to a human.
  • March 2020 (v3.0.0) – New ContentDesigner settings menu for changing QnABot configuration, new Elicit Response feature allows QnABot to support data collection and triage by asking questions and processing the answers,  new ‘Document Chaining’ rules allow QnABot to automatically advance to the next question with support for conditional branching, interaction in multiple languages now enhanced with automatic translations and support for multiple language Alexa voice skills, and the ability to simplify tuning by disabling use of the answer field in scoring results.
  • February 2020 (v2.6.0) – Use Amazon Kendra to find answers from document sources when a curated answer can’t be found in the QnABot Elastic Search index,  and introducing support for interaction in multiple languages.
  • November 2019 (v2.4.0) – Customizable configuration settings, minimized need to rebuild Lex bot when adding new content, improved accuracy using keyword filters, configurable response when answer isn’t found, improved handling of user feedback with integrated thumbs up/down buttons in web client, automated question testing in Content Designer, support variable substitution and conditional answers using ‘handlebars’ templates in Content Designer.
  • November 2018 – Buttons on response cards, eliminate need to retrain Alexa skills for new question, and minor UI improvements.
  • June 2018 – Markdown (rich text), SSML (Speech markup), usage and user feedback logging and dashboard.
  • May 2018 – New version of QnABot that contains bug fixes, a new look for the user interface, and additional features, including support for follow-up questions and extensibility with Lambda hook functions.

Additional Reading & Viewing

ANNOUNCEMENT
AWS QnABot is now an official AWS Solution Implementation.
To learn more about secure one-click deployment with the solution’s AWS CloudFormation template, select Get Started

About the Authors

Bob Strahan is a Principal Solutions Architect for AWS Language AI Services.

Bob Potterveld is a Principal Consultant for AWS Professional Services.

John Calhoun is an Associate Solutions Architect for the AWS Public Sector Partners team.