Custom App Series - Step 1 - Building a Custom App

Objective

The purpose of this document is to describe how to create an app in the VoiceWorx. After going through this document, you should be able to create custom app for channels such as Amazon Alexa, Google Assistant, Amazon Lex, Twilio and Slack.

Pre-requisites

You should have a connection and/or a Data Source established.

Scenario

You want to build an Amazon Alexa Skill where you can ask for a person’s phone number. All the phone numbers are stored in a Data Source, and for simplicity of this documents, it is assumed that the user has established a connection between the Data Source and the VoiceWorx Platform

We want to create a skill where the following commands should return a phone number:

“Get phone number for John Doe?”

“Find me the contact number for Doctor John Doe.”

Terminologies

• Intent

• Utterance

• Slot

• Entities

• Methods

• Input

Intent

Intent is the task the user wants to accomplish. Intent is not a specific word; it is the overall goal the user is trying to achieve. In our example, our intent is to find a phone number by name.

Utterance

A user can convey an intent by saying various phrases. In our example, we are going to use the two above mentioned utterances.

Slots

Slots are variables contained in intent. In our example, the slot is the name of the person whose phone number we are trying to find.

A screenshot of a cell phone Description automatically generated

Entities

Entities are the synonyms/variations for the slots. They define the various ways a user can specify an intent. For example, in our use case, the user can say the name of the person as ‘John Doe’ or ‘Doctor John Doe.’

Methods

Methods are the tasks performed on the database. Examples are search, put, push, delete etc.

Inputs

Inputs are slot mappings to the methods. VoiceWorx gets ‘slots’ from channels such as Alexa, Google Assistant or chatbots and then has to map these to methods for task execution. Inputs can contain multiple Input parameters.

Step 1: Create an App

Creating a custom app that can be consumed from an external platform like Alexa or Lex, includes the following steps

• Connect System (Data Source Integration)

• Create App

• Create the App Methods

• Add intents to the App

• Add Slots to the App

• Define Utterance

• Define Input

• Create Entities for App Slots (This is optional)

Step 2: Set up a Data Source

1. Login to the VoiceWorx platform, go to Integration menu and select Connect System. In the resulting page, click connect external systems

1. In the resulting popup, choose “Custom” from the “Select External System” and choose “Rest API Service” from the Select System Type option then click connect system.

1. Add the web API endpoint , username and password and click “Validate System” to ensure you have access to the web API endpoint.

ApiName: ContactFinder

Authorization Type: Basic Auth

Base API URL: https://demo.voiceworx.ai

Basic Auth Settings: Your VoiceWorx username

Password: Your VoiceWorx password

AuthorizationURL : https://demo.voiceworx.ai/api/contacts

Create Custom App in Voiceworx.ai

1. To create a custom app in VoiceWorx click on “Custom Apps” menu and select “Manage Apps”.

2. Click “New Custom App” button

1. Provide following details and click on Save.

Name: ContactFinder

Custom App Type: Search

Category: None

1. In the top menu tabs, select “Data Sources” then “Create New Data Source”. Provide the following details:

Name: ContactFinderDS

Integration Configuration: Rest API Service : Contact Finder ( integration configured in Step 2)

1. Click on methods and create new methods. Enter the following in the fields

   1. Name: GetPhoneNumberByName

   2. Request Type: GET

   3. Query Path: ?name={{Person}}

   4. Result Type: Record

   5. Method Path: /api/contacts

   6. Result Template: {{Person}}

   7. Empty Result Template:

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

Step 3: Creating an Intent

Navigate to the ‘Intents’ tab and click on the ‘Create New Intent’ button.

Parameter	Sample Value	Info
Name	PhoneByName	Any name that conveys the intent
Intent Type	Search/Custom/Survey	Purpose of the intent
Intent Action	Execute Method	Action that the user wants to perform
Data Source	Drop-down list	Select the respective Data Source
Data Source Method	Drop-down list	Select appropriate method for the Data Source

Step 4: Create Slot

Navigate to the ‘Slots’ tab and select your intent from the drop-down list. Then click on the ‘Create New Slot’ button.

Parameter	Sample Value	Info
Name	Person	Any Name for the slot
Reprompt Message	person name?	Message to display when slot is not understood
Type	Text	Select type of variable from drop-down
Custom Skill	ContactFinder	The skill associated with the slot
Intent	PhoneByName	Intent associated with the slot

Step 3: Creating Utterances

Navigate to the ‘Utterances’ tab and select the intent from the drop-down list for which you’re creating utterances. Then click on ‘Create New Utterance.’

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

Parameter	Sample Value	Info
Value		Utterance that will invoke an action
Custom Skill	ContactFinder	The skill associated with the utterance
Intent	PhoneByName	Intent associated with the utterance

You can add as many utterances as you would like.

Step 4: Mapping Inputs

Navigate to the ‘Inputs’ tab and click on ‘Create New Input.’

Parameter	Sample Value	Info
Name	Person	-
Custom Skill	ContactFinder	The skill associated with the input
Intent	PhoneByName	Intent associated with the input
Data Source	ContactFinderDS	Data Source associated with the input
Data Source Method	Person	Data Source method you want to invoke