AWS Machine Learning Blog

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

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.

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) to make your questions and answers searchable. When a user asks a question, the Amazon ES powerful full-text 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.
  • Troubleshoot and tune QnABot content to minimize the chances of getting wrong answers.
  • Enrich your answers with images and web links.

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.

Deploying QnABot

Use this AWS CloudFormation button to launch QnABot in AWS Region us-east-1:

Note: At the time of writing, only the us-east-1 Region is supported.

The source code is available in our GitHub repository.

In the AWS Management Console, on the CloudFormation Parameters page, enter a password to assign to the QnABot Content Designer Admin user. The password must have a length of at least 8 characters, and contain upper-case and lower-case characters, plus numbers and special characters.

Choose Next twice to display the Review page.

Select the acknowledgement checkbox, and choose Create to deploy QnABot.

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

  • Amazon Elasticsearch Service domain to store and search your content (1 x t2.small.elasticsearch). Cost approx. $0.036/hour – free tier eligible.
    NOTE: For production use, increase node count to ensure your Amazon ES domain is fault tolerant. For more information, see Configuring Amazon ES Domains.
  • Amazon S3 buckets to host the QnABot web UIs.
  • Amazon Lex Bot to provide natural language processing.
  • AWS Lambda functions used to administer QnABot content and to find answers to questions.
  • Amazon API Gateway REST APIs used by the web UIs.
  • Amazon Cognito configured to authenticate clients and provide temporary AWS credentials.
  • Amazon CloudFront distribution used for websites and API endpoints.

When the deployment is complete (after about 60 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.

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 a 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 from the Outputs tab of the master CloudFormation stack.
  2. Log in with username Admin, and the password you set when you launched the stack.
  3. Choose Add.
  4. Enter the id: QnaBot.001
    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 Save tool (upper right).
  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/Export, then Import URL, and enter the URL:
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 Lex web UI which 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.
  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 QnABot?”
    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, Amazon Dash Wand, 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), choose Lex/Alexa and then Alexa Instructions:

Follow the displayed instructions, step by step, to create an Alexa skill in your Amazon account. It will take you just a few minutes.

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.

Troubleshooting and tuning

Tuning answers using the Content Designer

QnABot attempts to match a user’s question to the list of questions and answers stored in Amazon ES by the Content Designer. QnABot uses  Amazon ES 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 matching the user’s question to both the question and the answer fields of the stored items, giving more weight to any matches found in the question field.

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 test. Observe that the highest scoring answer is not Admin.001.
  5. Now find and choose the lesser ranked 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 (upper right), and then the add question (+) tool under the first question on the left:
  7. Enter the new question: How can I edit items, and choose the save tool (upper right).
  8. Try the same question again, by choosing test (top of the page).
  9. Success! This time Admin.001 has the highest score.
    Try asking the question again in the Lex Web UI. This time you’ll get the desired answer.

Tuning the Bot’s Natural Language Processing

When you ask QnABot a question, it’s processed and transcribed by either Lex or Alexa using a Natural Language Processing (NLP) engine. QnABot initially trains the NLP 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.)

However, occasionally you might find that you want to say things to QnABot that it doesn’t understand and is unable to process. You might notice that the transcription shown in the web client or the Alexa app isn’t accurate, or that QnABot asks you to repeat what you just said.

If this happens, it is time to re-train the NLP. QnABot can generate additional training data automatically using questions from all the items you have added.

Retrain Lex

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

  1. Using the Lex Web Client UI (voice or text chat), state: “I need to change some answers
  2. In the last exercise, QnABot returned the wrong answer, but this time, it simply replies: “Sorry, can you please repeat that.” If you repeat the same statement, you will get an error message like, “Sorry, I could not understand. Goodbye.
    This is a symptom of the fact that the default bot is not trained to understand a statement in this form.
  3. Log in to the Content Designer, open item “Admin.001,” choose the Edit tool, choose the add question (+) tool, and add the statement as a new question: I need to change some answers.
    Save the update using the Save tool.
  4. Choose Lex/Alexa, then choose Rebuild Lex Bot. Wait for the rebuild to complete.
  5. Now try again, using the Lex Web Client UI to state “I need to change some answers.” Since the new statement has been added to the QnABot training set, you’ll see that it is no longer rejected, and that QnABot now responds with an appropriate answer.

Retrain Alexa

Update the training data set for Alexa, using the Amazon Developer console to edit the Custom Slot Type values for your skill.

  1. Log in to the Content Designer UI webpage, choose Lex/Alexa, and then choose Alexa Instructions.
  2. Find Custom Slot Type: EXAMPLE_QUESTIONS, and choose Copy to Clip Board:
  3. Sign in to the Amazon Developer Console, open your QnABot Alexa skill, go to InteractionModel, and replace the values for the EXAMPLE_QUESTIONS Custom Slot Type by pasting the new values from your clipboard. Choose Save to save the updates.

Using CloudWatch to monitor and troubleshoot

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.

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 Questions, and enter QnABot in the Filter to display just the items with IDs that start with the characters “QnABot”:
  1. Now, choose Import /Export, and Export Filtered to generate and save a JSON file containing the filtered items:
  2. Open the exported file in a text editor and inspect the JSON structure.
  1. 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": ""
  1. In the Content Designer, choose Import/Export, and Import Local. 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.
  2. In the Content Designer, enter QnABot in the filter field, and inspect the newly imported item, QnABot.003.

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 new 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. Enter attachment:
    1. Title: Echo Show
    2. ImageUrl:
  6. Save the new item.
  7. Use the Web UI to ask: “What is an Echo Show?”
    You’ll see the photograph displayed in the web UI chat.
  8. 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.
  9. 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).

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.”

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.

Lex Web Client UI

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 (see the discussion of “Tuning the Bot’s Natural Language Processing” 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 an Amazon CloudFront distribution.

An Amazon API Gateway endpoint sitting behind the same CloudFront distribution 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 Amazon ES query containing the transcribed question. The following example shows the query. The query attempts to find the best match from all the questions and answers you’ve previously provided, using Amazon ES relevance scoring. Matches found in the text of stored questions are given greater weight than matches found in the text of the stored answers.

    "size": 10,
    "from": 0,
    "query": {
        "multi_match": {
            "query": "How can I include pictures in Q and A Bot answers",
            "fields": [

The Bot fulfillment Lambda function uses the answer field 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, defining a single intent with a single slot.

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, or, if an Echo Show is used, on the touchscreen.

Content Designer UI

The QnABot Content Designer UI is also deployed to an Amazon S3 bucket accessed via the same Amazon CloudFront distribution as the Client UI, 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:

  • Usage metrics: Implement custom metrics to track which questions and topics are accessed most frequently.
  • Capture user feedback: Allow the user to report errors in answers, or to report when a given answer didn’t address the question that was asked.
  • 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.
  • Topic context memory: Add support for follow-up questions. For example, after asking, “What is the Echo Show?” the follow-up question, “How much does it cost?” would be assumed to apply to the Echo Show context.
  • 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 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.
  • Integrate QnABot with Amazon Connect: Lower your support center call wait times by automating answers to frequently asked questions, using QnABot within an Amazon Connect contact flow. (See Amazon Connect and Amazon Lex Integration.) You can also use popular messaging platforms to interact with QnABot.

About the Amazon Lex web UI

The QnABot web UI uses the aws-lex-web-ui GitHub repository. This repository provides the code that enables the web page to interact with the Amazon Lex bot, and handles audio capture and playback on webRTC-supported  web browsers.

You can use the Lex web UI to integrate QnABot as a component into your own website:

For more information, review the README file.

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.


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 or using any Alexa-enabled device.

Now you can try it with your own questions and answers! Please use the comments link to share your experiences with the QnABot – we’d love to hear from you!

Additional Reading

About the Authors

Bob Strahan is a Senior Consultant for AWS Professional Services. John Calhoun is an Associate Solutions Architect for the AWS Public Sector Partners team. They work with our customers and partners to provide leadership on a variety of projects, helping them shorten their time to value when using AWS.