# Amazon Lex Integration ### **Objective:** This document will demonstrate how to use the Custom App feature of iX Hello. ### **Introduction to API:** iX Hello can integrate with external platform via Web API’s. For this example, we will use 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 APIs. ### **Goal:** Our goal is to demonstrate the capability of iX Hello 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 2. **An iX Hello Account** For steps to create an account, follow the steps [here](https://docs.ixhello.com/ixhc/general/ix-hello-create-account-original) 1. **AWS-Account - Access Key, Secret access key and AWS Region Name**\ To be able to connect to Amazon Lex from iX Hello, 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 You can also refer to the simplified iX Hello IAM documentation [here](https://docs.ixhello.com/ixhc/aws-iam-users) ### **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 email for signup across the 3 channels below. Step 1-2 below are compulsory. 1. [Sign up for AWS account](https://console.aws.amazon.com/lex/) (Part of pre-requisites) 2. Sign up for iX Hello (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 iX Hello 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 iX Hello, use left navigation menu and open **Integration** > **Connect System**. On the resulting page, click **Add New Connection**.

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

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

4. 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**.

2. Populate the App Custom App screen and press **Save**:

3. In the Custom App listing, click on the new Contact Finder listing. 4. Open the **Data Sources** tab and press **Create New Data Source**.

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

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

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

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

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

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

11. 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. 12. Open the **Input** tab and press **Create New Input**

13. Populate the New Custom Input window.

**Name:** Person **Custom App:** ContactFinder **Custom Intent:** PhoneByName **Data Source:** ContactFinderDS **Data Source Method:** GetPhoneNumberByName 14. For the Slot you have created, now create a corresponding parameter by clicking on Manage Parameters.

15. Press **+ Input Parameter**

16. 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**.

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

3. Click **Save**. You will return to the App Publishing page. 4. Click on the three dots on the right side of the Contact Finder line. A menu will open.

5. Select **Publish to Lex**

6. 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) 7. 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. 8. When finished, click **Publish To Lex V2.** It may take a few minutes to create.

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

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

5. Start testing by writing utterance in the chat area and lex will connect to the app configured in the iX Hello 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.