Comment on page

Amazon Lex Integration


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

Introduction to API:

The VoiceWorx platform can integrate with external platform via web API’s and to demonstrate this capability, we have created a demo API endpoint (https://demo.voiceworx.ai/api/Contacts) in our demo web app “demo.voiceworx.ai”. 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 in demo.voiceworx.ai
Web App URL : http://demo.voiceworx.ai
Here is a sample contact in the database.


Our goal is to demonstrate the capability of the VoiceWorx platform to integrate with external platforms and perform CRUD operations against them via web API calls. We will create an Alexa Skill 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 in demo.voiceworx.ai. Note: the example uses Basic Authentication so username/passwords to the external resource is required.


  1. 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
AWS Accounts Include 12 Months of Free Tier Access
  1. 1.
    A VoiceWorx Account
For steps to create a VoiceWorx account, follow the steps at https://docs.voiceworx.ai/general/voiceworx-create-account
  1. 1.
    AWS Account - Access Key, Secret access key and AWS Region Name To be able to connect to Amazon Lex from the VoiceWorx platform, one AWS IAM user is required and user should have the required permissions to access Lex service.
Following is a json document which you can use to create an IAM policy and assign it to the IAM user in the AWS console.
"Version": "2012-10-17",
"Statement": [
"Sid": "VoiceWorx",
"Effect": "Allow",
"Action": [
"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 VoiceWorx documentation at https://docs.voiceworx.ai/aws-iam-users


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. 1.
    Sign up for AWS account (Part of pre-requisites)
  2. 2.
    Sign up for VoiceWorx platform (Part of pre-requisites)
  3. 3.
    Setup connection to Amazon Lex
  4. 4.
    Setup connection to the external web API
  5. 5.
    Create a custom skill in Voiceworx.
  6. 6.
    Publish the skill
  7. 7.
    Test the Amazon Lex skill.

Setup connection to Amazon Lex

Login to the VoiceWorx portal at https://portal.voiceworx.ai
To Configure Lex, browse to: Integration > Connect System > Connect External System in the VoiceWorx platform and select options as shown below.
Once you click on “Connect System” button, you will be redirected to the configuration screen where you need to provide connection information as shown below.
If you do not have this information ready, please refer to the pre-requisites #4
The table below explains each of the inputs shown on this screen.
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
AWS Region Name. The Lex service will be used in this region.
When used to publish the skill, it will be published in this region.
Fill the required information and click on “Validate and Save Settings” button, this will validate the details and if it is correct, integration will be saved, and you will be redirected to the integrations listing page as shown below.
Now the Lex connection is ready to use for future usage.

Setup connection to the external web API

  1. 1.
    Login to the VoiceWorx platform, use left navigation menu and click “Integration” then select “Connect System”. In the resulting page, click “Connect External Systems”.
  1. 1.
    In “Connect External System” select or do the following:
Select Integration Category: Custom
Select System Type: Rest API Service
Click: Connect System.
Graphical user interface, text, application Description automatically generated
  1. 1.
    Once in “Rest API Service Setup” select or enter the following:
System Instance Name: ContactFinder
Authorization Type: Basic Auth
Add Web API URL: https://demo.voiceworx.ai
Under Basic Auth Settings
Enter Username and Password
Click: Validate System to ensure you have access to the web API endpoint.
Click on Validate System and Click on Save after the connection is validated.
  1. 1.
    Once validated, you should be able to see Save button, click on it to save the connection.

Create Custom Skill in Voiceworx.ai

  1. 1.
    To create a custom app, use left navigation menu and click “Custom Apps” then select “Manage Apps”. Then click “New Custom App”.
  1. 1.
    Now add Custom Skill by doing the following:
Name: Contact Finder
Custom Skill Type: Search
Category: None
Click: Save
  1. 1.
    In the top menu tabs, select “Data Sources” then “Create New Data Source”. Select or enter the following:
Name: ContactFinderDS
Integration Configuration: Rest API Service: ContactFinder (integration configured in Step 2)
Manage Connections to create the external platform WebAPI integration
Click: Save
  1. 1.
    In the top menu tabs, select “Methods” then select “Create New Methods”.
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
    • Method Path: /api/contacts
    • 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. 1.
    Let’s test if the method is extracting the contact information correctly. Click on Test button.
Fill the following parameter and click on Method Test, then on Result section, click on Result tab.
Person : Martin
  1. 1.
    In the top menu tabs, select “Intents” and “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. 1.
    In the top menu tabs, select “Slots” and select “Create New Slot”.
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. 1.
    In the top menu tabs, select “Utterance” and select “Create New Utterance”. Utterance are words spoken to launch specific intents.
Now input or select the following:
Value: get phone number for {Person}
Custom Skill: ContactFinder
Intent: PhoneByName
Click: Save
Important: 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. 1.
    In the top menu tabs, select “Input” and select “Create New Input”.Then input or select the following:
Name: Person
Custom Skill: ContactFinder
Custom Intent: PhoneByName
Data Source: ContactFinderDS
Data Source Method: GetPhoneNumberByName
You will be able to view the created input as below:
For the Slot you have created, now create a corresponding parameter by clicking on Manage Parameters.
Create an Input Parameter and fill the following details:
Name: Person
Parameter: Person
Data Type:Text
Click on Save
You shall have the input parameter here.

Publish to Amazon Lex

  1. 1.
    To publish to Amazon Lex,select “Publish” in the top menu tabs then click “Add Skill Publishing”. Then input or select the following:
External Skill Name: ContactFinder. (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.)
Skill Type: Select Search
Channel: Select Amazon Lex
Version: Lex V1
Uncheck: Auto Publish (Next step explains what happens if you keep it checked)
Optional: Replace all placeholder values in all “Message”. Uncheck all the settings shown in the second image below.
Click: Save.
  1. 1.
    In the top menu tabs select “Publish” then click “Publish to Lex”, this will redirect you to the Publish skill to Amazon Lex screen.
  2. 2.
    Once you are on Publish Skill to Amazon Lex, select and do the following:
Selected Skill: Contact Finder (Should be pre-selected)
External Skill Name: Contact Finder (Read only, should be pre-selected)
Select Amazon Lex Account: Lex
Select the Lex account you have already setup. If not, you can do it by clicking on “Add New Lex Account” button and following the steps.
Click: Publish To Lex
Note: In previous step#23, if you have checked “Auto Publish”, you will be directly getting this screen. (In other words, step#24 will be skipped or auto executed)
  1. 1.
    On the resulting screen, ensure that a success message shows for the publishing steps before clicking the “Go To Lex Skill”. If success message not shown, click “Go To Skill Publishing” to fix any issue shown in publishing result.

Test the skill on Amazon Lex

  1. 1.
    On the Amazon Lex bot page, ensure “Build Completed” else you may not be able to Test the bot.
Once you are on Lex, you should see a screen like this,
  1. 1.
    Make sure it’s displaying skill name ContactFinder at the top left and then click on the Test Chatbot option at the right side. Click on Text Chatbot and you should see Test bot screen as shown below.
  2. 2.
    Start testing by writing utterance in the chat area and lex will connect to the skill configured in the VoiceWorx platform and you should get relevant response.
You have successfully completed building a Custom App and publishing to Amazon Lex.