Developing and distributing an Alexa Skill (Part 1)

Despite my protests, my wife went ahead and bought an Alexa Echo for the house. I didn’t like giving Amazon access to so much personal data, and still don’t, but now, having used the device for a month or so, it has become helpful.

After you get over the unsavory way in which Alexa tries to sell you amazon stuff, and the frustration of a stuttered or hesitant sentence not being recognized, the utility of having a live mic that can process inquiries in real time is undoubtedly useful, and it’s also fun (my son likes asking it what a blue whale sounds like).

Alexa is at its best when used simply. Single queries, not conversations, quips, not chapters, reading, not writing.

Amazon has made the development pretty easy, but unfortunately, it is fragmented across multiple offerings which was the main issue I had approaching the platform.

The utility I wanted early on was the ability to ask for verses from the New American Bible, and not the King James version which is missing several books. You can take a look at the outcome here.

And what follows is the path I took to develop my Alexa Skill that can do lookup a verse in the New American Bible (Revised Edition)…

Creating a new skill

First, go to https://developer.amazon.com and create an account.

Once logged-in, visit the Developer Console. There you will see the Alexa option in the navbar, and choose Alexa Skills Kit.

amazon-dev-console_navbar-alexa

Under the Alexa Skills listing, click the Create Skill button:

amazon-dev-console_alexa-skills_create-skill.jpg

In the next menu you can choose a sample app to start with. I would definitely recommend choosing the Fact Skill as it has the minimal point of entry. As far as I can tell, the biggest difference between them besides the source code that it creates with, is the Intent settings that are also created.

alexa-skills_choose-template

This will land you on the Skill’s dashboard page:

alexa-skills_skill-dashboard

On the left side navigation, you will see the elements that compose your skill, from a meta-data standpoint. All of these boil down the JSON that appears in the JSON Editor, which comes in handy when you need to edit some of the Utterances, or if you want to quickly copy a Skill’s settings into another skill.

Also in the sidebar (not shown in screen above), is the Endpoint configuration link. This is the URL where Amazon’s servers will look for your app’s code to handle the launch request.

Where does the skill app code go?

The skill has to point to a URL which is hosted either by AWS or on your own server. That URL needs to handle specific requests.

I used the AWS Lambda function option, which the Amazon developer site encourages, for a variety of reasons; most notably is that the free-tier offers a lot of usage for no cost. However, you can point it to a different URL where your server is hosted, or an ngrok.io endpoint to do local development. I explored this, but ended up going with the Lambda option, because it removed some of the unknowns, and I wanted to get up and running with least amount of effort.

System and custom Intents

When you develop a skill, you will need to handle a few system level Intents. These are like system events that occur depending on how your app is used. They can get pretty advanced, such as doing media playback, but that’s out of scope for us here.

The Fact Skill creates most of the Intents you need to handle, and includes one custom Intent to drive the core function of the app: to speak a random fact.

In addition to your own custom Intents, the Intents you will need to handle in your app are

  • AMAZON.CancelIntent
  • AMAZON.HelpIntent
  • AMAZON.StopIntent
  • LaunchRequest
  • SessionEndedRequest

Notice that the last two listed do not appear in the sidebar of the out-of-the-box Intents for the Fact Skill template. But they will need to be handled within the app.

Invocation of the skill

The invocation is how Alexa will launch your app. This is not so straightforward.

Alexa will launch your app given certain launch phrases such as “open”, “ask”, “start”, “launch”, etc, and the Invocation Name is the phrase that will map to your Skill. So if your skill is named “My Awesome Skill”, your invocation name could be simply “my awesome skill”, or you can make it different from the Skill name, such as “the awesomest skill,” whereby the full invocation would be

Alexa, open the awesomest skill.
alexa-skills_invocation-setting.jpg

Skill Utterances and Slots

When you want to try your skill, you need to launch it first. In the case of the out-of-the-box Fact Skill, the app doesn’t have need for an interaction, it simply blurts out one of a bunch of space facts.

When you develop, you should prompt the user for input when they launch the app. This input will then be matched against the Utterances you’ve added to the Skill. This will then be fed into the Intent that the matched Utterance maps to, and will be available as an event “slot” parameter.

If you click on the GetNewFactIntent, you are taken to a page where you can both rename the Intent (or you can just delete it create a new one), and then populate the Utterances for it.

alexa-skills_utterances_rename

In our case, we are going to create a couple ways to state how awesome something is.

As you type in the new Sample Utterance field, you can use the curly brackets to create a slot, which is the variable that will be populated by the user when he interacts with your skill. The utterance that gets matched and populated depends on the formation of the spoken sentence.

Let’s create a one to ten utterance with the following slot

{OneOutOfTen} out of ten
alexa-skills_utterances.jpg

I set the slot type to AMAZON.NUMBER so that it will be populated with an integer value.

I’m gonna make two ways of assessing awesomeness of a thing, the first is a number from 1 to 10 using the AMAZON.NUMBER slot type, the second is a custom slot type which I will call AwesomeType, and it will allow me to make a list of phrases which map to 1 to 10 numbers. Finally, I will create a slot for the thing which is being assessed using the AMAZON.SearchQuery which will use Alexa’s voice recognition to resolve a string phrase.

First, to create the custom slot type, click the add button next to the Slot Types menu item in the left sidebar.

Fill in a name for the type (no spaces):

alexa-skills_slot-type-create

Next you can add values in one of two ways:

  1. by entering them one at a time, or
  2. by using the bulk import, which receives a CSV file.

I prefer the second option, whereby the developer can load in a tab delimited file (without headers). The first column is the value which Alexa will use speech recognition to match, the second is the ID which is what will be sent to your app’s function (the Name is also sent in), and any following column is a synonym which Alexa will use alternately to map to the same ID (or value if no ID is provided). So the CSV would look like this:

Value1  ID1     Synonym1        Synonym2        (etc)

With the field populated, my slot type looks like this:

alexa-skills_slot-type_values

So Alexa will look for one of these values to populate the AwesomeType of one of my Utterances, which are as follows:

alexa-skills_utterances-list.jpg

So

  • {Thing} will use Amazon speech recognition to deliver a string phrase
  • {OneOutOfTen} will resolve to an integer value
  • {AwesomeType} will resolve to one of my field options which will include an ID that I can parse into an integer

So I have one Custom Intent and 5 built-in ones, one of which is optional; AMAZON.FallbackIntent, which can be used in the event that Alexa cannot understand what you said. It’s probably a good idea to handle this with at least a “Sorry, I couldn’t understand that kind of awesomeness” message.

Make sure to save the model using the Save Model button at the top of the page.

Creating an AWS Lambda function

Save the model, and then hop to https://aws.amazon.com and sign up for an account. Once you’ve done that, you can create a Lambda function which will be used to host your app.

Under the AWS Console, click on the services menu on the top navbar and select Lambda from the drop down menu:

aws-services_menu.jpg

On the listing for functions, click Create Function. Then on the Create Function page, select Blueprints, and then enter “alexa” in the search filter and choose alexa-skill-kit-sdk-factskill from the results, and click Configure:

aws-services_lambda_create-function

On the next screen you will enter the Basic Information of the Lambda; the name of the Lambda function (no spaces), and also choose a Role (which has the permissions for which the function to be called). I just click through which looks like this:

aws-services_lambda_role-access

Allow the IAM Role, and then you will return to the Basic Information screen:

aws-services_lambda_create-function_basic-information

Syncing the Lamba function with the Alexa Skill

After this, you will be taken to the Lambda editing page, where you will see printed at the top, the ARN code of the Lambda function. You will need to copy this and enter it into the Endpoint screen of your Alexa Skill later:

aws-services_lambda_add-trigger

On this edit page, you will need to add a Alexa Skills Kit trigger from the Add Triggers menu. You will see that when you do this, you will be prompted to configure the trigger using the Skill ID of your Alexa Skill:

aws-services_lambda_configure-trigger

So you need to have open both the Alexa Developer Console and the AWS Lambda Editor open to do this next part.

  1. In the Alexa Developer Console, click the Endpoint option in the leftside navigation, and copy the Skill ID you see listed and
  2. Paste it in the AWS Lambda Editor‘s trigger configuration field, and click Add there. Then Save it using the Save button near the ARN code at the top of the page.
  3. In the AWS Lambda Editor, copy the ARN code that appears at the top of the page, and
  4. Paste it in the Alexa Developer Console‘s Endpoint configuration form’s Default Region field, then save it using the Save Endpoint button that appears at the top of the page. You should see a green Skill Manifest Saved Successfully toast message appear.

Note on Default Region: I’ve been using East 1 (N. Virginia). I don’t know if choosing another region has any impact but I have read some users complaining about region issues, possibly between resources, not sure, but I stuck to East 1.

Back to the AWS Lambda Editor, you now need to code your app…!

I will tackle this in Part 2.

Buy Me A Coffee
If this guide was helpful, please consider a little tip

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s