Amazon Lex Integration

Objective:

This document will demonstrate how to use the Custom App feature of ixHello.

Introduction to API:

ixHello can integrate with external platform via Web API’s. For this example, we will use https://jsonplaceholder.typicode.com/users in our demo web app. We created multiple API endpoints for Contacts module and will be using the endpoint that searches an underlying Contacts database and returns the contact number of a specific person.

The demo web app that we created has the ability to perform CRUD operations against the underlying Contacts database that is triggered by calls to the exposed contact API’s.

Goal:

Our goal is to demonstrate the capability of ixHello to integrate with external platforms and perform CRUD operations against them via Web API calls. We will create a Lex app called Contact Finder. This Alexa app will look up and return a person’s number that is stored in the contacts database and is accessible via the contacts API endpoints. Note: the example uses Basic Authentication so username/passwords to the external resource is required.

Pre-requisites:

1. An active AWS-Account

You should have an active AWS-Account. If you do not have it, you can create an AWS account at https://portal.aws.amazon.com/billing/signup#/start

1. An ixHello Account

For steps to create an account, follow the steps here

1. AWS-Account - Access Key, Secret access key and AWS Region Name To be able to connect to Amazon Lex from ixHello, one AWS IAM user is required and user should have the required permissions to access Lex service.

The following JSON document will need to be added as an IAM permission policy and assigned to the IAM user in the AWS console.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "ixHello", "Effect": "Allow", "Action": [ "lex:*", "lambda:*", "iam:*" ], "Resource": "*" } ] }

For more information on creating IAM users and assigning policies, refer to the AWS official documentation https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/

You can also refer to the simplified ixHello IAM documentation here

Steps:

The following shows the general steps/activities that will be carried out in setting up this integration. Note: It is advisable to use same E-Mail for signup across the 3 channels below. Step 1-2 below are compulsory.

1. Sign up for AWS account (Part of pre-requisites)
2. Sign up for ixHello (Part of pre-requisites)

3. Setup connection to Amazon Lex

4. Setup connection to the external web API

5. Create a custom App.

6. Publish the app

7. Test the Amazon Lex app.

Setup connection to Amazon Lex

Login to ixHello

To Configure Lex, browse to: Integration > Connect System and press Add New Connection.

Select Amazon Lex from the dropdown and press Next.

Fill out the Configuration screen.

The table below explains each of the inputs shown on this screen.

Input	Information
Service Instance Name	You can give any value of your choice.
Consumer Key	This is your AWS-Access key ID
Consumer Secret	This is your AWS-Secret access key
Region	AWS Region Name: ex. us-west-1. The Lex service will be used in this region. When used to publish the app, it will be published in this region.

Fill the required information and click on Validate and Save Settings. If the details are correct, the integration will be saved, and you will be redirected back to the integrations listing page.

The Lex connection is ready to use for future usage.

Setup connection to the external web API

1. Log-in to ixHello, use left navigation menu and open Integration > Connect System. On the resulting page, click Add New Connection.

1. For the new connection, select REST API Service from the dropdown list and press Next:

1. The REST API Service Setup screen opens. Give a Service Instance Name of ContactFinder. For the demo URL of ttps://jsonplaceholder.typicode.com/users, the Authorization type will be No Auth. Press Validate System when finished

1. Once validated, click on Save.

Create Custom App

1. To create a custom app, use left navigation menu and open Apps > Custom Apps. Press New Custom App.

1. Populate the App Custom App screen and press Save:

1. In the Custom App listing, click on the new Contact Finder listing.

2. Open the Data Sources tab and press Create New Data Source.

1. Name the new DataSource ContactFinderDS. For Integration Configuration, use the REST API Service created earlier. Press Save

1. In the top menu tabs, open Methods. Make sure the REST API option is selected in the dropdown, then press Create New Method.

• Provide following details in the resulting Create Method box and click on Save.

  • Name:GetPhoneNumberByName

  • Request Type: GET

  • Query Path: ?name={{Person}}

  • Result Type: Record

  • Empty Result Template: Sorry the searched contact could not be found. How else can I help you?

  • Result Template: {{Person}} contact number is {{Phone}}. How else can I help you?

  • Click: Save

1. To test if the method is extracting the contact information correctly, scroll down and enter Leanne Graham in the Person field. Press Test.

1. In the top menu tabs, open the Intents tab and press Create New Intent.

Then select or enter the following:

Name: PhoneByName

Intent Type: Search

Intent Action: Execute Method

DataSource: ContactFinderDS

DataSource Method: GetPhoneNumberByName

Click: Save

1. Open the Slots tab and press Create New Slot.

Populate the fields. Note the Reprompt message is what Alexa will ask if it can’t fill/resolve the person slot. Then select or enter the following:

Name: Person

Slot Order: Blank

Reprompt Message: person name?

Type: Text

Custom App: ContactFinder

Intent: PhoneByName

Click: Save

1. Open the Utterance tab and press Create New Utterance. Utterances are words spoken to launch specific intents.

1. Now input or select the following:

Value: get phone number for {Person}

Custom App: ContactFinder

Intent: PhoneByName

Click: Save

Note: To insert slot in an utterance, type ‘{‘and a drop-down of available slots will appear.

You can add as many utterances as you would like.

1. Open the Input tab and press Create New Input

1. Populate the New Custom Input window.

Name: Person

Custom App: ContactFinder

Custom Intent: PhoneByName

Data Source: ContactFinderDS

Data Source Method: GetPhoneNumberByName

1. For the Slot you have created, now create a corresponding parameter by clicking on Manage Parameters.

1. Press + Input Parameter

1. Add the details:

Name: Person
Parameter: Person
Data Type: Text
Click on Save

Publish to Amazon Lex

1. To publish to Amazon Lex, open the Publish tab and click Add App Publishing.

1. Enter the following:

External App Name: Contact Finder. (This will be the name of the bot in Lex, therefore, make it unique and different from the names of your other bots on Amazon Lex.)

Description: (optional)

App Type: Search

Channel: Amazon Lex

Version: Lex V2

Uncheck: Auto Publish (Next step explains what happens if you keep it checked)

Optional: Replace the placeholder values in all Messages.

1. Click Save. You will return to the App Publishing page.

2. Click on the three dots on the right side of the Contact Finder line. A menu will open.

1. Select Publish to Lex

1. The Publish App To Amazon Lex screen appears:

Selected App: Contact Finder (Should be pre-selected)

External App Name: Contact Finder (Read only, should be pre-selected)

Amazon Lex Version: V2

Select Amazon Lex Account: Amazon Lex Integration (created earlier)

1. Select the Lex account you have already set up. If not, you can do it by clicking on “Add New Lex Account” button and following the steps.

2. When finished, click Publish To Lex V2. It may take a few minutes to create.

1. On the resulting screen, ensure that a success message shows for the publishing steps before clicking the “Go to Lex App”. If success message not shown, click “Go to App Publishing” to fix any issue shown in publishing result

Test the app on Amazon Lex

1. On the app publishing results page, a Go To LexV2 Console, will appear as shown.

1. Click on it, you will be redirected to the newly created Lex bot on the AWS console.

2. On the Amazon Lex bot page, ensure “Build Completed”. If not completed, then the bot will be unable to test. Once in Lex, you should land on this screen.

1. Make sure it’s displaying the correct app name at the top left and then click “Test Chatbot” option at the right side. Click “Text Chatbot” then the test bot screen will appear as shown below.

1. Start testing by writing utterance in the chat area and lex will connect to the app configured in the ixHello platform. At this time a relevant response will be received.

Congratulations!

You have successfully completed building a Custom App and published it to Amazon Lex.