Contact Finder Skill

Objective:

This document will help you use the Custom Skill feature of the Voiceworx platform to create an Alexa skill app.

Introduction to API:

The Voiceworx platform can connect to any API and you can also use the Custom Skill option to quickly build an Alexa app.

To demonstrate this capability, we have created a contact demo API endpoint in our demo web app “demo.voiceworx.ai”. We created multiple endpoints for Contacts module and will be using the endpoint that searches the Contacts database and returns the contact number of a specific person.

The demo web app that we created has modules to create, edit and delete contacts. We went ahead and added couple of contacts

Web App URL : http://demo.voiceworx.ai Contact Finder : https://demo.voiceworx.ai/api/Contacts?Name={Name} Here is a sample contact that we added using the web app url.

Goal:

Our goal is to create an Alexa app called “Contact finder”. This Alexa app must look up the person’s number from our contactfinder app and return the contact number.

Steps

Before starting you need to have an account for Amazon, Alexa and VoiceWorx. To create one, please follow the steps by clicking here, here and here respectively.

Setup connection to API and setup custom skill on Voiceworx platform.
Link alexa.amazon to developer.amazon.com
Test the Alexa skill.

Create Custom Skill in Voiceworx.ai

Create your skill and integrate it with an external API. To do that, click on “Setup Custom skill”.

The Custom Skill home page is displayed.

Create Custom Skill

This page will ultimately list all your Custom Skills. For now, the list is empty. Click the “Create New Custom Skill” button to get started.

A pop-up window appears. Create a skill name and type and click “Save”.

Note: Skill name in developer.Amazon.com and portal.voiceworx.ai must be the same.

Connect Custom API

In the top menu, click “Home”.

Click the “Connect Custom API” button to integrate custom APIs from any Enterprise Application.

Next, click the “Connect to External Systems” button to manage external system connections.

A pop-up window appears. Fill all the fields as listed below and click the “Validate System” button.

Integration Category : Custom Service Type : Rest API Service System Instance Name : <API Name> Base API URL : <URL> Authorization Type :<Basic Auth> Username :<demo@voiceworx.ai> Password :<registered password> Authorization Resource URL : <URL>

Upon successful validation, you will get a message stating, “Your Credentials are valid” if not, cross-check the credentials you entered in the form fields. Then, click the “Connect System” button.

Now, the Manage External System Connections should list the recently added external API.

Create Data Source

Choose Custom Skills and then click “Setup Custom skill”.

You need to create a new Data Source to enable your custom skill. Click the “Select” button to select the skill name.

The page will reload to display your Custom Skills list, of which you have only one so far. Select the Custom Skill Name by clicking the “Select” button next to it.

Now the Current Skill name is updated to the selected Skill name “<contactfinder>”. Previously, it was “SELECT”. Next click “Data Sources” from the top menu.

Selects “Create New Data Source”. This enables your Custom Skill to integrate with external systems.

Name your Data Source and Select the Integration Configuration type.

Once the Data Source is created, click the “Configure Methods” button.

Manage Data Source Methods

To create methods for the Data Source, click the “Create New Method” button. Methods are used to specify individual operations and parameters which are supported by the external Data Source you are connecting to.

In the pop-up window fill all the fields as listed below and click “Save”.

Name : <Any Name1> Data Source : <API Source> Result Type : Record Request Type : GET Method Path :<API> Query Path : ?Name={{Person}} Result Template : <Mention the parameter, for the value to be fetched in that API>

After you create your Methods, you need to manage your Results. Select “Manage Results”.

A pop-up window appears. Click “Add New Result”.

Another window appears to Manage Results. Fill all the fields as listed below and click “Save”.

Result Name : <Any Name2> Result Path : <Parameter Name> Data Type : <Depends on the value to be returned>

Create Intents

To interact with the custom skill, you need to create an intent. Click “Intents” from the top menu.

Select “Create New Intent”.

A window pops up, complete all the required fields to create an Intent and click “Save”.

Note: “Intent Name” in developer.Amazon.com and the “Intent Name” in portal.voiceworx.ai must be the same.

Create Search Parameters

Next step, select “Search” from the top menu.

Then select “Create New Search”

Next, you will need to manage the search parameters, select “Manage Parameters”.

Click the “Add New Search Parameter” button.

Note: the “parameter name” in portal.voiceworx.ai and the intent slot name in developer.Amazon.com must be the same. Fill all the required fields and click “Save”.

Click the “Back to Search Results” link.

Click the “Return to Custom Skills” link to choose the created custom skill.

Select “Entities” from the top menu.

Click “Add new Entity type”.

Complete and save all the required fields for the entity.

Publish the Custom Skill

Now, you need to publish External Skill. Click “Add Skill Publishing”.

Fill all the required fields as listed below and “Save”.

Note: The skill name must be kept the same in both portal.voiceworx.ai and developer.Amazon.com

External Skill Name :<AnyName> Skill Type : Search Channel : Alexa Custom Skill : <AnyName> Require Account Linking : Check Box

The next field is Skill ID. To get the value of Skill ID, open a new tab for developer.Amazon.com and click “Alexa”.

Select the menu item, “Skill Builders” and choose the “Developer Console” option.

You should now see the created skill “contactfinder”. Click “View Skill ID”.

A pop-up window displays the “contactfinder” skill ID. Copy that skill ID.

Paste the Skill ID in the Publish Skill screen at “portal.voiceworx.ai”. Fill the other fields as listed below and “Save”.

Welcome Message : <Welcome to <Skill Name> How can I help you?> Re-Prompt Message : <Hello please repeat again> Help Message : <Help> Goodbye Message : <Bye>