Repository files navigation

This is a sampleAmazon 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.

It can be used as a full page chatbot UI:

Or embedded into an existing site as a chatbot widget:

• 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
• Connect interactive messaging support

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.

These are the currently supported regions. Click a button to launch it in the desired region.

Region	Launch	CloudFormation Template
Northern Virginia		us-east-1
Oregon		us-west-2
Ireland		eu-west-1
Sydney		ap-southeast-2
Singapore		ap-southeast-1a
Seoul		ap-northeast-2
London		eu-west-2
Tokyo		ap-northeast-1
Frankfurt		eu-central-1
Canada (Central)		ca-central-1

By default, the CloudFormation templatecreates a sample Lex bot and aAmazon 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 theCloudFormationDeployment 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.

New regions supporting Lex only support Lex Version 2. A default install of Lex Web Ui with no target Bot specifiedattempts to install a sample Lex Version 1 Bot and will fail in these new regions. In regions adding Lex support, a Lex Version 2Bot should be deployed prior to deploying Lex Web UI.

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 theUsage andDeployment sections below for details.

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 theLibrariesandConfiguration sections before jumping to the codeexamples.

The list below describes the libraries produced by this project.Pre-built versions of the libraries are found under thedistdirectory 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 thelex-web-ui.js file under thedist directory. Itis bundled from the source under thelex-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'sREADMEfor 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 thelex-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

The chatbot UI component requires a configuration objectpointing to an existing Lex bot and to anAmazon 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 theChatBot UI ConfigurationLoading sectionof the loader library documentation and theConfiguration andCustomizationsection of the chatbot UI component documentation.

Lex Web UI supports bothListPicker and TimePicker templateTypes and can be sent using the same JSON structure as utilized by Connect.

ListPicker display in Web UI:

TimePicker in Web UI:

The examples below are organized around the following use cases:

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

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 (seeLibraries)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.

The loader library provides the easiest way to display the chatbot UI. Theentry point to this library is thelex-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 fromthedist 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 --><scriptsrc="./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.jsonnewChatBotUiLoader.FullPageLoader().load();</script>

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 thefull page fordescription of this API.

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

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 thelex-web-ui.jsJavaScript file. The UI CSS styles are contained in thelex-web-ui.cssfile. The component depends on theVue,Vuex,VuetifyandAWS 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 --><linkhref="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700|Material+Icons"rel="stylesheet"type="text/css"><!-- Vuetify CSS Dependencies --><linkhref="https://unpkg.com/vuetify@0.16.9/dist/vuetify.min.css"rel="stylesheet"type="text/css"><!-- LexWebUi CSS from dist directory --><linkhref="./lex-web-ui.css"rel="stylesheet"type="text/css"><!-- page specific LexWebUi styling --><styletype="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 --><divid="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    --><scriptsrc="https://unpkg.com/vue@2.5.3"></script><scriptsrc="https://unpkg.com/vuex@3.0.1"></script><scriptsrc="https://unpkg.com/vuetify@0.16.9"></script><scriptsrc="https://sdk.amazonaws.com/js/aws-sdk-2.149.0.min.js"></script><!-- LexWebUi Library from dist directory --><scriptsrc="./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.varconfig={cognito:{// Your Cognito Pool Id - this is required to provide AWS credentialspoolId:'<your cognito pool id>'},lex:{// Lex Bot Name in your accountv2BotId:'<your lex bot id>'}};// load the LexWebUi componentvarlexWebUi=newLexWebUi.Loader(config);// instantiate VuenewVue({el:'#lex-web-ui',store:lexWebUi.store,template:'<div><lex-web-ui/></div>',});</script></body></html>

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. Thelex-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 thedist directory of this repo are hosted in the samedirectory as the parent page. If hosting the iframe on the same domainas your parent page is desired, you must deploy the iframe code into yourown environment to allow the use of SAMEORIGIN configurations.

Please note that theloaderOptions variable has aniframeSrcPathfield which defines the path to the full page chatbot UI. This variablecan be pointed to a page like the one described in thestand-alonepage section.

<html><head><title>My Parent Page</title></head><body><h1>Welcome to my parent page</h1><!-- loader script --><scriptsrc="./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 constructorvarloaderOptions={// you can put the chatbot UI config in a JSON fileconfigUrl:'./chatbot-ui-loader-config.json',// the full page chatbot UI that will be iframediframeSrcPath:'./chatbot-index.html#/?lexWebUiEmbed=true'};// The following statement instantiates the IframeLoadervariframeLoader=newChatBotUiLoader.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.varchatbotUiConfig={ui:{// origin of the parent site where you are including the chatbot UI// set to window.location.origin since hosting on same siteparentOrigin: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 siteiframeOrigin:window.location.origin,},cognito:{// Your Cognito Pool Id - this is required to provide AWS credentialspoolId:'<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 accountv2BotId:'<your lex bot id>'}};// Call the load function which returns a promise that is resolved// once the component is loaded or is rejected if there is an erroriframeLoader.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 theparent.html page and theIframe Embedding documentation of theloader library.

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 thesrc/website directory. The pages includes theindex.html file which loads the chatbot UIin a stand-alone page and theparent.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.

This project provides a simple HTTP server to serve the sample site.You can run the server usingNode.js on your localmachine or a test server. Please note that running locally is only designedfor testing purposes as the localhost only runs on HTTP and does not usea secure HTTPs configuration.

The chatbot UI requires proper configuration values in the files locatedunder thesrc/config directory. Modify the values in thelex-web-ui-loader-config.json file under thesrc/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: {"v2BotId":"ABC123"}...

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 port8000, issue the command:

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

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

# runs on port 8000npm run dev

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

This project providesAWS 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.

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

If you want to modify or change LexWebUi functionality follow thisrelease process once you are satisfied and have tested your code modifications.You'll need to create an S3 bucket to hold the bootstrap artifacts. Replace "yourbootstrapbucketname" withthe name of your bucket to complete the upload.

npm installcd lex-web-uinpm installcd ../build./release.shexport BUCKET="yourbootstrapbucketname"./upload-bootstrap.sh

Note that "yourbootstrapbucket" (S3 bucket) must allow objects with public-read acl to be added. This approachis described in the image below. Please be aware of thesecurity implications of allowing public-read acl. Do not add any sensitive data into this bucket as it will be publicly readable.

Once you've uploaded your distribution to your own bootstrap bucket, you can launch an installation of LexWebUiin the AWS region where this bucket is located by using the master.yaml from your bootstrap bucket. You canalso update an existing LexWebUi installation by performing a stack update replacing the current template withthe template you just uploaded to your bootstrap bucket. Note that for either a fresh installation or an update,you need to change the BootstrapBucket parameter to be the name of your bootstrap bucket and the BootstrapPrefixparameter to be just "artifacts".

Two changes in version 0.19.0 are the ability to forward chat history as a transcript to anagent when Connect Live Chat is initiated. Details on use of the transcript can be found inConnect Live Chat Agent Readme. This version also updates theOPTIONS method in the API to configure CORS to only allow requests from the WebAppParentOrigin.

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

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.

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

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

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

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

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

• 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

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

• 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

• 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

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

• 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
• SeeCHANGELOG for additional details

• 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

• 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