Sample Amazon Lex Web Interface

Overview

This is a sample Amazon Lex web interface. It provides a chatbot UI component that can be integrated in your website. The interface allows a user to interact with a Lex bot directly from 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:

Features

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

Getting Started

The easiest way to test drive the chatbot UI is to deploy it using the AWS CloudFormation templates provided 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	<a target="_blank" href="https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3.amazonaws.com/aws-bigdata-blog/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml&stackName=lex-web-ui&param_BootstrapBucket=aws-bigdata-blog"><span><img height="24px" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png"/></span></a>	us-east-1
Oregon	<a target="_blank" href="https://us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/create/review?templateURL=https://s3.amazonaws.com/aws-bigdata-blog-replica-us-west-2/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml&stackName=lex-web-ui&param_BootstrapBucket=aws-bigdata-blog-replica-us-west-2"><span><img height="24px" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png"/></span></a>	us-west-2
Ireland	<a target="_blank" href="https://eu-west-1.console.aws.amazon.com/cloudformation/home?region=eu-west-1#/stacks/create/review?templateURL=https://s3.amazonaws.com/aws-bigdata-blog-replica-eu-west-1/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml&stackName=lex-web-ui&param_BootstrapBucket=aws-bigdata-blog-replica-eu-west-1"><span><img height="24px" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png"/></span></a>	eu-west-1
Sydney	<a target="_blank" href="https://ap-southeast-2.console.aws.amazon.com/cloudformation/home?region=ap-southeast-2#/stacks/create/review?templateURL=https://s3.amazonaws.com/aws-bigdata-blog-replica-ap-southeast-2/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml&stackName=lex-web-ui&param_BootstrapBucket=aws-bigdata-blog-replica-ap-southeast-2"><span><img height="24px" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png"/></span></a>	ap-southeast-2
Singapore	<a target="_blank" href="https://ap-southeast-1.console.aws.amazon.com/cloudformation/home?region=ap-southeast-1#/stacks/create/review?templateURL=https://s3.amazonaws.com/aws-bigdata-blog-replica-ap-southeast-1a/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml&stackName=lex-web-ui&param_BootstrapBucket=aws-bigdata-blog-replica-ap-southeast-1a"><span><img height="24px" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png"/></span></a>	ap-southeast-1a
Seoul	<a target="_blank" href="https://ap-northeast-2.console.aws.amazon.com/cloudformation/home?region=ap-northeast-2#/stacks/create/review?templateURL=https://s3.amazonaws.com/aws-bigdata-blog-replica-ap-northeast-2/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml&stackName=lex-web-ui&param_BootstrapBucket=aws-bigdata-blog-replica-ap-northeast-2"><span><img height="24px" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png"/></span></a>	ap-northeast-2
London	<a target="_blank" href="https://eu-west-2.console.aws.amazon.com/cloudformation/home?region=eu-west-2#/stacks/create/review?templateURL=https://s3.amazonaws.com/aws-bigdata-blog-replica-eu-west-2/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml&stackName=lex-web-ui&param_BootstrapBucket=aws-bigdata-blog-replica-eu-west-2"><span><img height="24px" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png"/></span></a>	eu-west-2
Tokyo	<a target="_blank" href="https://ap-northeast-1.console.aws.amazon.com/cloudformation/home?region=ap-northeast-1#/stacks/create/review?templateURL=https://s3.amazonaws.com/aws-bigdata-blog-replica-ap-northeast-1/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml&stackName=lex-web-ui&param_BootstrapBucket=aws-bigdata-blog-replica-ap-northeast-1"><span><img height="24px" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png"/></span></a>	ap-northeast-1
Frankfurt	<a target="_blank" href="https://eu-central-1.console.aws.amazon.com/cloudformation/home?region=eu-central-1#/stacks/create/review?templateURL=https://s3.amazonaws.com/aws-bigdata-blog-replica-eu-central-1/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml&stackName=lex-web-ui&param_BootstrapBucket=aws-bigdata-blog-replica-eu-central-1"><span><img height="24px" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png"/></span></a>	eu-central-1
Canada (Central)	<a target="_blank" href="https://ca-central-1.console.aws.amazon.com/cloudformation/home?region=ca-central-1#/stacks/create/review?templateURL=https://s3.amazonaws.com/aws-bigdata-blog-replica-ca-central-1/artifacts/aws-lex-web-ui/artifacts/templates/master.yaml&stackName=lex-web-ui&param_BootstrapBucket=aws-bigdata-blog-replica-ca-central-1"><span><img height="24px" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png"/></span></a>	ca-central-1

By default, the CloudFormation template creates a sample Lex bot and a Amazon Cognito Identity Pool to get you started. It copies the chatbot UI web application to an Amazon S3 bucket including a dynamically created configuration file. The CloudFormation stack outputs links to the demo and related configuration once deployed. See the CloudFormation Deployment section for details.

You can modify the configuration of the deployed demo site to customize the chatbot UI. It can also be further configured to be embedded it on your web site. See the sections below for code samples and a description of 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 specified attempts to install a sample Lex Version 1 Bot and will fail in these new regions. In regions adding Lex support, a Lex Version 2 Bot should be deployed prior to deploying Lex Web UI.

Integrating into your Site and Deploying

In addition to the CloudFormation deployment mentioned above, there are other methods to integrate and deploy this project. Here is a summary of the various methods:

#	Method	Description	Use Case
1	CloudFormation Deployment using the CloudFormation templates provided by this project	Fully automated deployment of a hosted web application to an S3 bucket with an optional CI/CD pipeline. By default, it also creates a Cognito Identity Pool and a sample Lex bot	Use when you want to have a infrastructure as code approach that automatically builds and configures the chatbot UI resources
2	Use the pre-built libraries from the dist directory of this repo	We provide a pre-built version of the chatbot UI component and a loader library that you can use on your web site as a stand alone page or as an embeddable iframe	Use when you have an existing site and want to add the chatbot UI to it by simply copying or referencing the library files
3	Use npm to install and use the chatbot UI as a Vue component	Enables developers to consume this project as an npm package that provides a Vue component. See the Npm Install and Vue Component Use section for details	Use when developing front-end based web applications built using JavaScript and bundled with tools such as webpack

See the Usage and Deployment sections below for details.

Usage

This project provides a set of JavaScript libraries used to dynamically insert the chatbot UI in a web page. The chatbot UI is loaded and customized by including these libraries in your code and calling their functions with configuration parameters.

The chatbot UI can be displayed either as a full page or embedded in an iframe. In this section, you will find a brief overview of the libraries and configuration parameters. It is useful to get familiar with the concepts described in the Libraries and Configuration sections before jumping to the code examples.

Libraries

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

Chatbot UI component. A UI widget packaged as a JavaScript reusable component that can be plugged in a web application. The library is provided by the lex-web-ui.js file under the dist directory. It is bundled from the source under the lex-web-ui directory. This library is geared to be used as an import in a webpack based web application but can also be instantiated directly in a web page provided that you manually load the dependencies and explicitly pass the configuration. See the component's README for details
Loader. A script that adds the chatbot UI component library described in the item above to a web page. It facilitates the configuration and dependency loading process. The library is provided by the lex-web-ui-loader.js file under the dist directory. It is bundled from the sources under the src/lex-web-ui-loader directory. This library is used by adding a few script tags to an HTML page. See the loader README for details

Configuration

The chatbot UI component requires a configuration object pointing to an existing Lex bot and to an Amazon Cognito Identity Pool to create credentials used to authenticate the Lex API calls from the browser. The configuration object is also used to customize its behavior and 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 the resources created in the deployment (i.e. Lex and Cognito).

You can override the configuration at run time by passing parameters to the library functions or using various dynamic configuration methods provided by the loader library (e.g. JSON file, events). For details, see the ChatBot UI Configuration Loading section of the loader library documentation and the Configuration and Customization section of the chatbot UI component documentation.

Connect Interactive Messaging

Lex Web UI supports both ListPicker 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:

Examples

The examples below are organized around the following use cases:

Stand-Alone Page
Iframe
Npm Install and Vue Component Use

Stand-Alone Page

To render the chatbot UI as a stand-alone full page, you can use two alternatives: 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 included directly into an HTML file to display a full page chatbot UI.

When you use the chatbot UI component directly, you have to manually load the component's dependencies and provide its configuration as a parameter. The loader library alternative provides more configuration options and automates the process of loading dependencies. It encapsulates the 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. The entry point to this library is the lex-web-ui-loader.js script. This script facilitates the process of loading run-time dependencies and configuration.

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

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, the FullPageComponentLoader now provides an API allowing a subset of events to be sent to the Lex Web UI Component. These events are ping and postText. See the full page for description of this API.

Stand-Alone details

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