Sample Amazon Lex Web Interface

sample Amazon Lex Web Interface

Overview

This is a sample Amazon Lexweb interface. It provides a chatbot UI component that can be integratedin your website. The interface allows a user to interact with a Lex bot directlyfrom a browser using text or voice.

Features include:

• Mobile ready responsive UI with full page or embeddable widget modes
• Support for voice and text with the ability to seamless switch fromone mode to the other
• Voice support provides automatic silence detection, transcriptionsand ability to interrupt responses and replay recordings
• Display of Lex response cards
• Ability to programmatically configure and interact with the chatbotUI using JavaScript

Changes in version 0.18.2

Add feature for connect live chat. Allow client to optionally interact with an agent via Connect.See Connect Live Chat Agent Readme for additional details.

Notable changes in version 0.18.1

The Lex Web Ui now supports configuration of multiple Lex V2 Bot Locale IDsusing a comma separated list in the parameter LexV2BotLocaleId. The default Locale IDis en_US. Other supported values are de_DE, en_AU, en_GB, es_419, es_ES, es_US, fr_CA,fr_FR, it_IT, and ja_JP. See "https://docs.aws.amazon.com/lexv2/latest/dg/lex2.0.pdf"for the current list of supported Locale IDs.

When multiple Locale IDs are specified in LexV2BotLocaleId, the Lex Web UI toolbar menuwill allow the user to select the locale to use. The user selected locale ID ispreserved across page refreshes. The locale selection menu items will be disabled ifthe user is the middle of completing an intent as the locale ID can't be changed at thistime. The selected locale ID will be displayed in the toolbar.

Lex Web Ui is now available in the Canada (Central) region - ca-central-1

For a complete list of fixes/changes in this version see CHANGELOG.md.

Fixes/changes in version 0.18.0

• Move from webpack V3 to webpack V4 in the lex-web-ui component.
• Move to npm version 7.10.0.
• Update component package versions.
• Resolve dependabot alerts.
• Fix to resolve update problem where Cognito Supported Identity Providers is reset to just Cognito. An updatewill now preserve the existing Supported Identity Providers.
• Set AWS sdk to version 2.875.0.
• Improve Lex V2 support to handle responseCard defined as a session attribute in sessionAttributes.appContext.responseCard.
• Removed support for AWS Mobile Hub based distribution.

Fixes/changes in version 0.17.9

• New support for Lex Version 2 Bots - added template parameters for V2 Bot Id, Bot Alias Id,and Locale Id. When a V1 Bot name is provided, the template will configure resources to usethe V1 bot. When the V1 Bot name is left empty and the V2 Bot parameters are specified, the templatewill configure resources to use the V2 Bot. V1 Bot parameters take precedence over V2 Bot parameters if bothare supplied.
• The Lex Web Ui can now be configured to send an initial utterance to the bot to get an intent started. Anew template parameter named WebAppConfBotInitialUtterance is available. If left empty, no initial utterance issent to the Bot which is the default behavior.
• Changed format of the date message displayed on a message to use "n min ago" to assist with accessibility whendisplaying this value.
• Changed behavior of ShouldLoadIframeMinimized setting. In prior releases, the last known state of the iframe took priorityover this setting. In this release, when ShouldLoadIframeMinimized is set to true and the parent page isloaded or refreshed, the Bot iframe will always appear minimized. If this parameter is set to false, the last known stateof the Bot is used to either show the iframe or minimize the iframe.
• Changed loginutils.js to prevent the parent page or the full page from looping if login fails through cognito.With this change, up to 5 attempts will be performed before failing with an alert message presented to the user.
• Support mixed case web ParentOrigin URLs and WebAppPath in Cognito user pool to prevent login failures due to case mismatch.
• Support multiple values for WebAppPath. This allows the LexWebUI with login enabled to be deployed on multiple pageson the same site (origin).
• Update the Cognito Callback and Signout URLs in the Cognito UserPool when ParentPageOrigin and WebAppPath parametersare updated in CloudFormation.

Fixes in version 0.17.8

• Fix for pipeline based deployments - issue 264 - template error
• Fix to full page web client (index.html) using forceLogin to require a redirect to login page
• Fix to move to python 3.8 Lambda Runtime for yaml CloudFormation template embedded functions which remove use of boto3 vendored library
• Add ability for Lex Web UI to automatically retry a request if the Lex bot times out after 30 seconds using a configurable number of attempts.By default the timeout retry feature is disabled. When enabled, the default retry count is 1.

Fixes in version 0.17.7

• Build script fix
• Move min button icon to the left of text

Fixes in version 0.17.6

• Additional fixes to support upgrades. Upgrades from 0.17.1 and above are supported.Older versions will need to perform a fresh install to migrate to this version.

Fixes in version 0.17.5

• Fix to allow use of CF template upgrade to disable WebAppConfHelp, WebAppConfPositiveFeedback, and WebAppConfNegativeFeedback
• Fix to improve resizing of lex-web-ui button at bottom of page when text is used in addition to icon

Features in version 0.17.4

• Improved upgrade support.
  • The CloudFormation upgrade stack operation from the AWS Console should now be used tochange configuration using the available parameters. After the upgrade is complete, thelex-web-ui-loader-config.json file deployed to the web app S3 bucket will be updatedwith the values specified in the template. Prior versions of the config file are archivedusing a date timestamp in the S3 bucket should you need to refer to prior configuration values.
  • Users can now upgrade to new versions of Lex-Web-Ui using the AWS CloudFormation consoleby replacing the template and specifying the S3 template location from the original regionalS3 bucket. As new releases of Lex-Web-Ui are published to the distribution repositories, youcan now upgrade to this version using the CloudFormation Upgrade/replace template process.
  • After an upgrade, the CloudFront distribution cache will need to be invalidated for the changes to be seenimmediately.
  • Regional upgrade distribution locations
    • us-east-1: https://aws-bigdata-blog.s3.amazonaws.com/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml
    • us-west-2: https://aws-bigdata-blog-replica-us-west-2.s3-us-west-2.amazonaws.com/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml
    • ap-northeast-1: https://aws-bigdata-blog-replica-ap-northeast-1.s3-ap-northeast-1.amazonaws.com/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml
    • ap-southeast-1a: https://aws-bigdata-blog-replica-ap-southeast-1a.s3-ap-southeast-1.amazonaws.com/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml
    • ap-southeast-2: https://aws-bigdata-blog-replica-ap-southeast-2.s3-ap-southeast-2.amazonaws.com/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml
    • eu-central-1: https://aws-bigdata-blog-replica-eu-central-1.s3.eu-central-1.amazonaws.com/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml
    • eu-west-1: https://aws-bigdata-blog-replica-eu-west-1.s3-eu-west-1.amazonaws.com/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml
    • eu-west-2: https://aws-bigdata-blog-replica-eu-west-2.s3.eu-west-2.amazonaws.com/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml
    • ca-central-1: https://aws-bigdata-blog-replica-ca-central-1.s3.ca-central-1.amazonaws.com/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml
• Chat history can now be preserved and redisplayed when the user comes back to the original parent pagehosting the Lex-Web-Ui. This features is controlled using the SaveHistory template parameter. Whenthis feature is enabled, a new menu is visible in the user interface that allows the user toclear chat history. The following are the methods you can enable this feature. Note that you cantoggle this feature on and off using the upgrade process.
  • During a new deployment, specify true for the Save History parameter
  • Using the new upgrade feature, specify true for Save History parameter in the CloudFormationconsole.
• Lambda function upgrade to Python 3.7.

Fixes in version 0.17.3

• Added loader config option (forceLogin) to templates which configures UI to require the user to authenticate through Cognito prior to using the bot.
• Added loader config option (minButtonContent) which allows text to be added to the button which appears on the parent page when the iframe is minimized.
• Added XRay support to Lambda functions.
• Added VPC actions to Lambda IAM Roles to support future deployment of Lambdas in VPC.
• Encrypted S3 buckets using AES-256 default KMS key
• Prebuilt deployments now available for Singapore, Tokyo, London, and Frankfurt regions

Fixes in version 0.17.2

• Added option to hide message bubble on button click
• Resolved current github dependabot security issues
• Use default encryption for all S3 buckets using AES-256 encryption
• Added instructions in readme for adding additional vue components

Fixes in version 0.17.1

• Create uniquely named Cognito UserPool on stack creation
• Removed display of Back button in title bar and instead provide a replay button using the text from priormessage directly in the message bubble. Back button can be re-enabled though configuration json if desired.
• Enhanced css attributes of the minimized chatbot button to help allow clicking on items in the parentwindow as well as selecting text next the button.

New Features in version 0.17.0

• Improved screen reader / accessibility features
• Added CloudFormation stack outputs for CloudFront and S3 bucket
• Use response card defined in session attribute "appContext" over that defined by Lex based response Card
• lex web ui now supports greater than 5 buttons when response card is defined in session attributes "appcontext"
• Updated dependent packages in package-lock.json identified by Dependabot security alerts
• Resolved additional CloudFront CORS issues
• See CHANGELOG for additional details

New Features in version 0.16.0

• Lex-web-ui now ships with cloudfront as the default distribution method
  • better load times
  • non public access to S3 bucket
  • better future integration to cloudfront features such as WAF and Lambda@Edge
• Updated package.json dependencies

New Features in version 0.15.0

• Moved to Webpack 4
• Changed default parameter ShowResponseCardTitle to be false - was default of true
• Added back default parameter BotAlias of '$LATEST'. The '$LATEST'alias should only be used for manual testing. Amazon Lex limitsthe number of runtime requests that you can make to the $LATEST version of the bot.

Toolbar Buttons

• Help Button

Ways the lex-web-ui chatbot can be deployed

It can be used as a full page chatbot UI:

Or embedded into an existing site as a chatbot widget:

Getting Started

The easiest way to test drive the chatbot UI is to deploy it using theAWS CloudFormation templatesprovided by this project. Once you have launched the CloudFormation stack,you will get a fully working demo site hosted in your account.

Click a button to launch it in the desired region

Region	Launch
Northern Virginia
Oregon
Ireland
Sydney
Singapore
London
Tokyo
Frankfurt
Canada (Central)

By default, the CloudFormation templatecreates a sample Lex bot and a Amazon Cognito IdentityPoolto get you started. It copies the chatbot UI web application to anAmazon S3 bucket including a dynamicallycreated configuration file. The CloudFormation stack outputs links tothe demo and related configuration once deployed. See the CloudFormationDeployment section for details.

You can modify the configuration of the deployed demo site to customizethe chatbot UI. It can also be further configured to be embedded it onyour web site. See the sections below for code samples and a descriptionof the configuration and deployment options.

Integrating into your Site and Deploying

In addition to the CloudFormation deployment mentioned above, there areother methods to integrate and deploy this project. Here is a summaryof the various methods:

See the Usage and Deployment sections below for details.

Usage

This project provides a set of JavaScript libraries used to dynamicallyinsert the chatbot UI in a web page. The chatbot UI is loaded andcustomized by including these libraries in your code and calling theirfunctions with configuration parameters.

The chatbot UI can be displayed either as a full page or embeddedin an iframe. In this section, you will find a brief overview ofthe libraries and configuration parameters. It is useful to getfamiliar with the concepts described in the Librariesand Configuration sections before jumping to the codeexamples.

Libraries

The list below describes the libraries produced by this project.Pre-built versions of the libraries are found under the distdirectory of this repository.

1. Chatbot UI component. A UI widget packaged as a JavaScript reusablecomponent that can be plugged in a web application. The library isprovided by the lex-web-ui.js file under the dist directory. Itis bundled from the source under the lex-web-uidirectory. This library is geared to be used as an import in a webpackbased web application but can also be instantiated directly in a web pageprovided that you manually load the dependencies and explicitly passthe configuration. See the component's READMEfor details
2. Loader. A script that adds the chatbot UI component librarydescribed in the item above to a web page. It facilitates theconfiguration and dependency loading process. The libraryis provided by the lex-web-ui-loader.js file under thedist directory. It is bundled from the sources under thesrc/lex-web-ui-loader directory. This libraryis used by adding a few script tags to an HTML page. See the loaderREADME for details

Configuration

The chatbot UI component requires a configuration objectpointing to an existing Lex bot and to an Amazon Cognito IdentityPoolto create credentials used to authenticate the Lex API calls from thebrowser. The configuration object is also used to customize its behaviorand UI elements of the chatbot UI component.

The CloudFormation deployment method, from this project,help with building a base configuration file. When deploying with it,the base configuration is automatically pointed to the theresources created in the deployment (i.e. Lex and Cognito).

You can override the configuration at run time by passingparameters to the library functions or using various dynamicconfiguration methods provided by the loader library (e.g. JSONfile, events). For details, see the ChatBot UI ConfigurationLoading sectionof the loader library documentation and the Configuration andCustomizationsection of the chatbot UI component documentation.

Examples

The examples below are organized around the following use cases:

1. Stand-Alone Page
2. Iframe
3. Npm Install and Vue Component Use

Stand-Alone Page

To render the chatbot UI as a stand-alone full page, you can use twoalternatives: 1) directly use the chatbot UI component library or 2)use the loader library. These libraries (see Libraries)provide pre-built JavaScript and CSS files that are ready to be includeddirectly into an HTML file to display a full page chatbot UI.

When you use the chatbot UI component directly, you have to manuallyload the component's dependencies and provide its configuration as aparameter. The loader library alternative provides more configurationoptions and automates the process of loading dependencies. It encapsulatesthe chatbot UI component in an automated load process.

Stand-Alone Page Using the Loader Library

The loader library provides the easiest way to display the chatbot UI. Theentry point to this library is the lex-web-ui-loader.js script. Thisscript facilitates the process of loading run-time dependencies andconfiguration.

If you deploy using the CloudFormation method, you willget an S3 bucket with the loader library script and related files in away that is ready to be used. Alternatively, you can copy the files fromthe dist directory of this repository to your web server and include theloader.

In its most simple setup, you can use the loader library like this:

<!-- include the loader library script -->
<script src="./lex-web-ui-loader.js"></script>
<script>
  /*
    The loader library creates a global object named ChatBotUiLoader
    It includes the FullPageLoader constructor
    An instance of FullPageLoader has the load function which kicks off
    the load process
  */

  // The following statement instantiate FullPageLoader and
  // calls the load function.
  // It is assumed that the configuration is present in the
  // default JSON file: ./lex-web-ui-loader-config.json
  new ChatBotUiLoader.FullPageLoader().load();
</script>

Stand-Alone API through the Loader Library

Similar to the iFrame loading technique described later, theFullPageComponentLoader now provides an API allowing a subset ofevents to be sent to the Lex Web UI Component. These events areping and postText. See the full page fordescription of this API.

Stand-Alone details

For more details and other code examples about using the loader scriptin a full page setup, see the full pagesection of the loader documentation. You can also see the source of theindex.html page used in the demo site.

Stand-Alone Page Directly Using the ChatBot UI Component

Directly loading the chatbot UI component works at a lower level thanusing the loader library as described above. This approach can be usedif you want to manually control the rendering, configuration anddependency loading process.

The entry point to the chatbot UI component is the lex-web-ui.jsJavaScript file. The UI CSS styles are contained in the lex-web-ui.cssfile. The component depends on the Vue,Vuex, Vuetifyand AWS SDK libraries. Youshould either host these dependencies on your site or load them from athird-party CDN.

The HTML code below is an illustration of directly loading the chatbot UIlibrary and its dependencies.

NOTE: The versions of the links below may need to be pointedto the latest supported versions.

<html>
  <head>
    <!-- Font Dependencies -->
    <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700|Material+Icons" rel="stylesheet" type="text/css">

    <!-- Vuetify CSS Dependencies -->
    <link href="https://unpkg.com/vuetify@0.16.9/dist/vuetify.min.css" rel="stylesheet" type="text/css">

    <!-- LexWebUi CSS from dist directory -->
    <link href="./lex-web-ui.css" rel="stylesheet" type="text/css">
    <!-- page specific LexWebUi styling -->
    <style type="text/css">
      #lex-web-ui-app { display: flex; height: 100%; width: 100%; }
      body, html { overflow-y: auto; overflow-x: hidden; }
    </style>
  </head>
  <body>
    <!-- application will be dynamically mounted here -->
    <div id="lex-web-ui"></div>

    <!--
      Vue, Vuex, Vuetifiy and AWS SDK dependencies must be loaded before lex-web-ui.js.
      Loading from third party CDN for quick testing
    -->
    <script src="https://unpkg.com/vue@2.5.3"></script>
    <script src="https://unpkg.com/vuex@3.0.1"></script>
    <script src="https://unpkg.com/vuetify@0.16.9"></script>
    <script src="https://sdk.amazonaws.com/js/aws-sdk-2.149.0.min.js"></script>

    <!-- LexWebUi Library from dist directory -->
    <script src="./lex-web-ui.js"></script>

    <!-- instantiate the web ui with a basic config -->
    <script>
      // LexWebUi supports numerous configuration options. Here
      // is an example using just a couple of the required options.
      var config = {
        cognito: {
          // Your Cognito Pool Id - this is required to provide AWS credentials
          poolId: '<your cognito pool id>'
        },
        lex: {
          // Lex Bot Name in your account
          botName: '<your lex bot name>'
        }
      };
      // load the LexWebUi component
      var lexWebUi = new LexWebUi.Loader(config);
      // instantiate Vue
      new Vue({
        el: '#lex-web-ui',
        store: lexWebUi.store,
        template: '<div id="lex-web-ui-app"><lex-web-ui/></div>',
      });
    </script>
  </body>
</html>

Iframe

You can embed the chatbot UI into an existing page using an iframe.This approach provides a self-contained widget that can interact withthe parent page hosting the iframe. The lex-web-ui-loader.js loaderlibrary provides the functionality to add it as an iframe in a page.

This loader script dynamically creates the iframe tag and supportspassing asynchronous configuration using events and JSON files. It alsoprovides an API between the iframe and the parent page which can be usedto pass Lex state and other events. These features are detailed in theIframe Embedding section of the library.

The HTML code below is a basic example of a parent page that adds thechatbot UI as an iframe. In this scenario, the libraries and relatedfiles from the dist directory of this repo are hosted in the samedirectory as the parent page.

Please note that the loaderOptions variable has an iframeSrcPathfield which defines the path to the full page chatbot UI. This variablecan be pointed to a page like the one described in the stand-alonepage section.

<html>
  <head>
    <title>My Parent Page</title>
  </head>
  <body>
    <h1>Welcome to my parent page</h1>
    <!-- loader script -->
    <script src="./lex-web-ui-loader.js"></script>
    <script>
      /*
        The loader library creates a global object named ChatBotUiLoader
        It includes the IframeLoader constructor
        An instance of IframeLoader has the load function which kicks off
        the load process
      */

      // options for the loader constructor
      var loaderOptions = {
        // you can put the chatbot UI config in a JSON file
        configUrl: './chatbot-ui-loader-config.json',

        // the full page chatbot UI that will be iframed
        iframeSrcPath: './chatbot-index.html#/?lexWebUiEmbed=true'
      };

      // The following statement instantiates the IframeLoader
      var iframeLoader = new ChatBotUiLoader.IframeLoader(loaderOptions);

      // chatbot UI config
      // The loader can also obtain these values from other sources such
      // as a JSON file or events. The configUrl variable in the
      // loaderOptions above can be used to put these config values in a file
      // instead of explicitly passing it as an argument.
      var chatbotUiConfig = {
        ui: {
          // origin of the parent site where you are including the chatbot UI
          // set to window.location.origin since hosting on same site
          parentOrigin: window.location.origin,
        },
        iframe: {
          // origin hosting the HTML file that will be embedded in the iframe
          // set to window.location.origin since hosting on same site
          iframeOrigin: window.location.origin,
        },
        cognito: {
          // Your Cognito Pool Id - this is required to provide AWS credentials
          poolId: '<your cognito pool id>'
        },
        connect: {
          contactFlowId : '<your contact flow id>',
          instanceId : '<your instance id>',
          apiGatewayEndpoint : '<your api gateway endpoint>',
        },
        lex: {
          // Lex Bot Name in your account
          botName: '<your lex bot name>'
        }
      };

      // Call the load function which returns a promise that is resolved
      // once the component is loaded or is rejected if there is an error
      iframeLoader.load(chatbotUiConfig)
        .then(function () {
          console.log('iframe loaded');
        })
        .catch(function (err) {
          console.error(err);
        });
    </script>
  </body>
</html>

For more examples showing how to include the chatbot UI as an iframe,see the source of the parent.html page and theIframe Embedding documentation of theloader library.

Npm Install and Vue Component Use

You can use the npm package manager toinstall this project. The npm installation provides a library that youcan import as a module into your JavaScript code. The component is builtas a reusable Vue plugin. This approach is gearedto be used in a webpack based project.

Package installation using npm:

# install npm package from github repo
npm install --save awslabs/aws-lex-web-ui
# you may need to install co-dependencies:
npm install --save vue vuex vuetify material-design-icons roboto-fontface

This is a quick example showing how to import the library in your project:

// assumes that a bundler like webpack will handle import/require
// using es6 module
import LexWebUi from 'aws-lex-web-ui';
// or using require
var LexWebUi = require('aws-lex-web-ui');
// import the debug non-minimized version
import LexWebUi from 'aws-lex-web-ui/dist/lex-web-ui';

The source of the chatbot UI component resides under thelex-web-ui directory. For further details about the chatbotUI component see its README file.

Sample Site

This repository provides a sample site that you can use as a basefor development. The site is a couple of HTML pages can be foundin the src/website directory. The pages includes theindex.html file which loads the chatbot UIin a stand-alone page and the parent.htmlwhich page loads the chatbot UI in an iframe.

These pages are the same ones that are deployed by the CloudFormationdeployment method in this project. It uses thelex-web-ui-loader.js loader library to display and configure the chatbotUI. You can run a development version of this sample site on your machine.

Running Locally

This project provides a simple HTTP server to serve the sample site.You can run the server using Node.js on your localmachine or a test server.

The chatbot UI requires proper configuration values in the files locatedunder the src/config directory. Modify the values in thelex-web-ui-loader-config.json file under the src/config directory.If you deployed the demo site using the CloudFormation templates providedby this project, you can copy the automatically generated config filesfrom the S3 buckets to your development host.

As a minimum,you would need to pass an existing Cognito Pool Idand Lex Bot name. For example, set the appropriate values in thesrc/config/lex-web-ui-loader-config.json file:

...
  cognito: {
    "poolId": "us-east-1:deadbeef-fade-babe-cafe-0123456789ab"
  },
  lex: {
    "botName": "myHelpBot"
  }
  ...

Before you run the local development server, you need to install thedevelopment dependencies with the command:

npm install

To start the HTTP server web on port 8000, issue the command:

# serves http://localhost:8000/index.html
# and http://localhost:8000/parent.html
npm start

If you want to hack the libraries under the src/lex-web-ui-loaderdirectory, the project provides a hot reloadable webpack devserver setup with thefollowing command:

# runs on port 8000
npm run dev

For a more advanced local host development and test environment, see theDependencies and Build Setupdocumentation of the chatbot UI component.

Deploying

This project provides AWS CloudFormationtemplates that can be used to launch a fully configured working demo site andrelated resources (e.g. Lex bot and Cognito Identity Pool).

The CloudFormation deployment is the preferred method as it allows toautomatically build, configure and deploy the application (including anoptional CI/CD pipeline) and it provides a higher degree of flexibilitywhen integrating with an existing environment.

CloudFormation Deployment

The CloudFormation stack creates a web app in an S3 bucket which youcan link from your site. The S3 bucket also hosts the configuration,JavaScript and CSS files which can be loaded by your existing webpages. The CloudFormation deployment is documented in theREADME file under the templatesdirectory.