# Custom App with Publishing to Alexa Contact Finder

## **Objective:**

This document will demonstrate how to use the Custom App feature of the ixHello 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](https://demo.voiceworx.ai/api/Contacts?Name=%7bName%7d)) 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](http://demo.voiceworx.ai/)

Contact Finder: [https://demo.voiceworx.ai/api/Contacts?Name={Name}](https://demo.voiceworx.ai/api/Contacts?Name=%7bName%7d)

Here is a sample contact in the database.

![](/files/-MlPr7lPGfWZzDcQ25yY)

## **Goal:**

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.

## **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 -3 below are compulsory.

1. [Sign up for Alexa account](http://alexa.amazon.com/)
2. [Sign up for Alexa developer account](https://signin.aws.amazon.com/signin?redirect_uri=https%3A%2F%2Fus-east-2.console.aws.amazon.com%2Fconsole%2Fhome%3Fregion%3Dus-east-2%26state%3DhashArgs%2523%26isauthcode%3Dtrue\&client_id=arn%3Aaws%3Aiam%3A%3A015428540659%3Auser%2Fhomepage\&forceMobileApp=0\&code_challenge=9nNXzyrNIGZEa88E12gdwP_z_GcXjUlexn0VjUc6Z_s\&code_challenge_method=SHA-256).
3. [Sign up for VoiceWorx platform](https://portal.voiceworx.ai/Account/Login?ReturnUrl=%2F)
4. Ensure you Login With Amazon (LWA) <https://developer.amazon.com/alexa/console/ask> account is setup by your admin. If you are the account admin, you can follow this instruction to set it up.
5. Set up connection to the external web API
6. Create a custom skill in Voiceworx.
7. Publish the skill
8. Test the Alexa skill.

## **Set up connection to the external web API**

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

![](/files/-MlPr7lQaZw8CTWgzDeV)

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]\(/files/-MlPr7lRk-KexH7PMsIq)

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.

![](/files/-MlPr7lScwW6VFrsdCDI)

Click on Validate System and Click on Save after the connection is validated.

![](/files/-MlPr7lTFMM4X0OCQJh-)

## **Create Custom App in Voiceworx.ai**

1. To create a custom app, use left navigation menu and click “**Custom Apps**” then select “**Manage Apps**”. Then click “**New Custom App**”.

![](/files/-MlPr7lUij2gOE77rbyl)

1. Now add Custom Skill by doing the following:

**Name:** Contact Finder

**Custom Skill Type**: Search

**Category**: None

**Click**: Save

![](/files/-MlPr7lVaoXwirOrDiQ-)

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 Servic&#x65;**:** ContactFinder (integration configured in Step 2)

**Manage Connections** to create the external platform WebAPI integration

**Click:** Save

![](/files/-MlPr7lWcWR_lFj-WOVw)

![](/files/-MlPr7lXEyn1BVYw6ioE)

1. In the top menu tabs, select “**Methods**” then select “**Create New Methods**”.

![](/files/-MlPr7lYn45tHqYz05rG)

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

![](/files/-MlPr7lZ1Pw1QSsgnY_c)

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

![](/files/-MlPr7l_c1ap-D3pqg82)

1. In the top menu tabs, select “**Intents**” and “**Create New Intent**”.

![](/files/-MlPr7laa3qYGl_cbqB4)

Then select or enter the following:

**Name:** PhoneByName

**Intent Type:** Search

**Intent Action:** Execute Method

**DataSource:** ContactFinderDS

**DataSource Method:** GetPhoneNumberByName

**Click:** Save

![](/files/-MlPr7lbXVtij_7SA1Ld)

1. In the top menu tabs, select “**Slots**” and select “**Create New Slot**”.

![](/files/-MlPr7lcSYzk8ncwX4bX)

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

![](/files/-MlPr7ldtQYU33V1Pb11)

1. In the top menu tabs, select “**Utterance**” and select “**Create New Utterance**”. Utterance are words spoken to launch specific intents.

![](/files/-MlPr7le1M21HwayoUEp)

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 **‘{‘**&#x61;nd a drop-down of available slots will appear.

![](/files/-MlPr7lfQbBPxacIpA3s)

You can add as many utterances as you would like.

![](/files/-MlPr7lgtXO50q_YIqfL)

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

![](/files/-MlPr7lhUUNs79x-Gc-H)

You will be able to view the created input as below:

![](/files/-MlPr7liDlg4BtPJhLbe)

## **Publish to Alexa**

1. To publish to Alexa, select “**Publish**” in the top menu tabs then click “**Add App Publishing**”. Then input or select the following:

![](/files/-MlPr7ljgWZCV5WMJ-ZU)

Fill the following details to create publish.

**External Skill Name**: ContactFinder. (This will be the name of the skill in Alexa. Therefore, make it unique and different from the names of your other skills in Alexa.)

**Skill Type**: Select Search

**Channel**: Select Alexa

**Uncheck the following**: Require account linking, Auto Publish

**Skill Invocation Name**: ContactFinder. (This will be what users say to launch your skill in Alexa. It must be in lower case alphabets cannot contain **START, BEGIN, STOP, EXIT, LAUNCH** and cannot contain number or special characters.)

**Optional**: Replace all placeholder values in all “Message”. Uncheck all the settings shown in the second image below.

**Click**: Save.

![](/files/-MlPr7lk4OV5D-FIKGUt)

1. Set the needed Alexa permissions/features for your app in VoiceWorx by checking/unchecking the setting checkboxes in the publishing page as shown below.

![](/files/-MlPr7llgV78EwZxjBLn)

**Click**: Save.

1. In the top menu tabs select “**Publish**” then click “**Publish to Alexa**”.

![](/files/-MlPr7lmfzt815Xhzbbr)

1. Once in Publish Skill to Amazon Alexa select and do the following:

**Selected Skill**: Contact Finder

**Select Amazon Account:** LWA Config

Select the LWA account setup by your admin or the one you set up in step 4 above.

**Click**: Publish To Alexa

![](/files/-MlPr7lnNYWnpcdahYHn)

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

!\[Graphical user interface, text, application

Description automatically generated]\(/files/-MlPr7lo6JyNOjthf\_Mb)

1. On the Alexa skill page, ensure “**Full Build Successful**” message is shown in bottom right corner before starting to test skill.

!\[Graphical user interface, text, website

Description automatically generated]\(/files/-MlPr7lpxK0Fq3YZAJlx)

1. Go to “**test**” tab in the top menu, then below “**test**” tab change the skill test status from “**Off**” to “**Development**”.

![](/files/-MlPr7lq8Tp3p-ggK_D6)

1. Invoke skill by typing the invocation name (Contact Finder) inserted in the publishing step in Voiceworx. If the invocation is successful, your configured welcome message will be displayed in the developer console.

!\[A screenshot of a computer screen

Description automatically generated]\(/files/-MlPr7lrK7XVllA4lo3v)

![](/files/-MlPr7ls0Y_cfAbHLHeH)

**Congratulations! You have successfully completed building a**

**Custom Skill and publishing to Alexa.**

*Note: Keywords ‘App’ and ‘Skill’ are used interchangeably.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ixhello.com/ixhc/apps/custom-skill-with-publishing-to-alex-contact-finder.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.