[Tutorial] Build an Alexa Skill in Node.js with Jovo

By Jan König (@einkoenig), published on July 28th, 2017, last modified on June 1st, 2018 at 4:03 pm
Tags: Amazon Alexa, Tutorials

In this Alexa Skill tutorial for beginners, you will learn how to build a project for the popular voice platform from scratch. We will cover the essentials of building an app for Alexa, how to set everything up on the Amazon Developer Portal, and how to use Jovo to build your Skill’s logic.

See also: Build a Google Action in Node.js with Jovo

What you’ll learn

About Jovo: Jovo is an open source Node.js development framework for voice applications for both Amazon Alexa and Google Assistant. Check out the GitHub repository or the documentation, if you’re interested in learning more.

What We’re Building

To get you started as quickly as possible, we’re going to create a simple Skill that responds with “Hello World!”

Please note: This is a tutorial for beginners and explains the essential steps of Alexa Skill development in detail. If you already have experience with Alexa and just want to learn more about how to use Jovo, either skip the first few sections and go right to Code the Skill, or take a look at the Jovo Documentation.

 

1) How do Alexa Skills Work?

In this section, you will learn more about the architecture of Alexa and how users interact with its Skills. An Alexa Skill interaction basically consists of speech input (your user’s request) and output (your Skill’s response).

There are a few steps that happen before a user’s speech input is reaching your Skill. The voice input process (from left to right) consists of three stages that happen at three different places:

Alexa Input Process: Alexa enabled device passes speech input to the Alexa API which passes a request to your Skill Code

  1. A user talking to an Alexa enabled device (speech input), which is passed to…
  2. the Alexa API which understands what the user wants (through natural language understanding), and creates a request, which is passed to…
  3. your Skill code which knows what to do with the request.

The third stage is where your magic is happening. The voice output process (from right to left) goes back and passes the stages again:

Alexa Output Process: You return a request to the Alexa API which creates a speech output and passes it to the Alexa enabled device

  1. Your Skill code now turns the input into a desired output and returns a response to…
  2. the Alexa API, which turns this response into speech via text-to-speech, sending sound output to…
  3. the Alexa enabled device, where your user is happily waiting and listening

In order to make the Skill work, we first need to configure it, so that the Alexa API knows which data to pass to your application (and where to pass it). We will do this on the Amazon Developer Portal.

 

2) Create a Skill on the Amazon Developer Portal

The Amazon Developer Portal is the console where you can add your Skill as a project, configure the language model, test if it’s working, and publish it to the Alexa Skill Store.

Please note: With the new Jovo CLI, you don’t have to go through all the steps in the Developer Portal, as you can create a new Skill project and Interaction Model with the jovo deploy command. However, we believe for starters it’s good training to understand how Alexa Skills work.

Let’s get started:

a) Log in with your Amazon Developer Account

Go to developer.amazon.com and click “Developer Console” on the upper right:

Amazon Developer Portal

Now either sign in with your Amazon Developer account or create a new one. To simplify things, make sure to use the same account that’s registered with your Alexa enabled device (if possible) for more seamless testing.

Amazon Developer Portal: Sign in ScreenGreat! You should now have access to your account. This is what your dashboard of the Amazon Developer Console looks like:

Amazon Developer Console: Dashboard

b) Create a new Skill

Now it’s time to create a new project on the developer console. Click on the “Alexa” menu item in the navigation bar and choose “Alexa Skill Kit” to access your Alexa Skills:

Amazon Developer Console: Alexa Section

Let’s create a new Skill by clicking on the blue button to the upper right:

The next step is to give the Skill a name:

Alexa is available in different countries and languages, like the US, UK, and Germany. A Skill can have more than one language (although you have to configure all the following steps again). Make sure to use the language that is also associated to the Amazon account that is linked to your Alexa enabled device, so you can test it without any problems. In our case, it will be English (U.S.) for the United States:

After this step, choose Custom as Skill model:

In the following steps, we will create a language model that works with Alexa.

 

 

3) Create a Language Model

After successfully creating the Skill, the screen looks like this:

As you can see in the left sidebar, an Interaction Model consists of an Invocation, Intents, and Slot Types.

But first, let’s take a look at how natural language understanding (NLU) with Alexa works.

a) An Introduction to Alexa Interaction Models

Alexa helps you with several steps in processing input. First, it takes a user’s speech and transforms it into written text (speech to text). Afterward, it uses a language model to make sense out of what the user means (natural language understanding).

A simple interaction model for Alexa consists of the following elements: Invocationintents, utterances, and slots.

Invocation

There are two types of names for your Alexa Skill: While the first, the Name is the one people can see in their Alexa app and the Alexa Skill Store, the Invocation Name is the one that is used by your users to access your Skill:

How an Alexa Invocation Name Works

Intents

An intent is something a user wants to achieve while talking to your product. It is the basic meaning that can be stripped away from the sentence or phrase the user is telling you. And there can be several ways to end up at that specific intent.

FindRestaurantIntent with three example utterances

For example, a FindRestaurantIntent from the image above could have different ways how users could express it. In the case of Alexa language models, these are called utterances:

Utterances

An utterance (sometimes called user expression) is the actual sentence a user is saying. There are often a large variety of utterances that fit into the same intent. And sometimes it can even be a little more variable. This is when slots come into play:

Slots

No matter if I’m looking for a super cheap place, a pizza spot that serves Pabst Blue Ribbon, or a dinner restaurant to bring a date, generally speaking it serves one purpose (user intent): to find a restaurant. However, the user is passing some more specific information that can be used for a better user experience. These are called slots:

FindRestaurantIntent with utterances and slots

 

 b) Choose an Invocation

Make sure to choose an invocation name that can be understood by Alexa. For this simple tutorial, we can just go with HelloWorld (name, done during Skill creation) and hello world (invocation name):

 

c) Create a HelloWorldIntent

For our simple voice app we only need to create two intents and add a few sample utterances, as well as a slot. So let’s dive into the Amazon Developer Console and do this.

Click on the “+ Add” button to add our “HelloWorldIntent”:

Alexa Developer Console: HelloWorldIntent

And add the following example phrases to the “Sample Utterances“:

Alexa Developer Console: HelloWorldIntent

Create the “MyNameIsIntent” next with the following utterances:

Alexa Developer Console: MyNameIsIntent

After you did that, you will see that the console automatically added an intent slot called “name”, but we still have to assign a slot type, so our Skill knows what kind of input it should execpt. In our case it’s “AMAZON.US_FIRST_NAME”:

Alexa Developer Console: Slot Type

That’s all we need. Now click on the “Build Model” button on the top:

Alexa Developer Console: Build Model

 

4) Build Your Skill’s Code

Now let’s build the logic of our Alexa Skill.

We’re going to use our Jovo Framework which works for both Alexa Skills and Actions on Google Home.

a) Install the Jovo CLI

The Jovo Command Line Tools (see the GitHub repository) offer a great starting point for your voice application, as it makes it easy to create new projects from templates.

$ npm install -g jovo-cli

This should be downloaded and installed now (see our documentation for more information like technical requirements). After the installation, you can test if everything worked with the following command:

This should look like this:

b) Create a new Project

Let’s create a new project. You can see from the feature above that it’s possible to create new projects with this command (the “helloworld” template is the default template and will clone our Jovo Sample App into the specified directory):

c) A First Look at the Project

Let’s take a look at the code provided by the sample application. This is what the folder structure looks like:

For now, you only have to touch the app.js file. This is where all the configurations and app logic will happen. Learn more about the App Architecture here.

Let’s take a look at the App Logic first:

d) Understanding the App Logic

The setHandler method is where you will spend most of your time when you’re building the logic behind your Alexa Skill. It already has a “HelloWorldIntent” and a “MyNameIsIntent”, as you can see below:

What’s happening here? When your skill is opened, it triggers the LAUNCH-intent, which contains a toIntent call to switch to the HelloWorldIntent. The ask method is used to ask a user for a name.

If a user responds with a name, the MyNameIsIntent is triggered. Here, the tell method is called to respond to your users with a “Nice to meet you!”

 

6) App Configuration: Where to Run Your Code

So where do we send the response to? Let’s switch tabs once again and take a look at the Amazon Developer Console, this time the Endpoint section:

To make a connection between the Alexa API and your application, you need to either upload your code to AWS Lambda, or provide an HTTPS endpoint (a webhook).

Jovo supports both. For local prototyping and debugging, we recommend using HTTPS (which we are going to describe in the next step), but you can also jump to the Lambda section.

a) App Configuration: Local Prototyping with the Jovo Webhook

The index.js comes with off-the-shelf server support so that you can start developing locally as easy as possible.

Let’s try that out with the following command (make sure to go into the project directory first):

This will start the express server and look like this:

As you can see above, Jovo is automatically creating a link to your local server: the Jovo Webhook. Paste the link into the field of the Amazon Developer Console and choose the second option for the SSL Certificate (the link Jovo webhook provides you is a secure subdomain):

Great! Your voice app is now running locally and ready to test. If you’re interested in how to set up Lambda, read further. If you want to dive right into the testing, jump to “Hello World!”

 

b) App Configuration: Host your Code on AWS Lambda

AWS Lambda is a serverless hosting solution by Amazon. Many Skills are hosted on this platform, as it is a cheap alternative to other hosting providers, and also Amazon offers additional credits for Alexa Skill developers. In this section, you’ll learn how to host your Skill on Lambda. This usually takes a few steps, so be prepared. If you only want to get an output for the first time, go back up to Local Prototyping.

In the next steps, we are going to create a new Lambda function on the AWS Developer Console.

Create a Lambda Function

Go to aws.amazon.com and log into your account (or create a new one):

AWS Portal

Go to the AWS Management Console:

AWS Services

Search for “lambda” or go directly to console.aws.amazon.com/lambda:

AWS Lambda Functions

Click “Create a Lambda function”, choose “Author from scratch” and fill out the form:

AWS Lambda Blueprints

You can either choose an existing role (if you have one already), or create a new one. We’re going to create one from a template and call it “myNewRole” with no special policy templates:

Now it’s time to configure your Lambda function. Let’s start by adding the Alexa Skills Kit as a trigger:

AWS Lambda: Configure Triggers

You can enable skill ID verification, if you want, but it’s not neccessary.

AWS Lambda: Skill ID verification

Upload Your Code

Now let’s get to the fun part. You can either enter to code inline, upload a zip, or upload a file from Amazon S3.  As we’re using other dependencies like the jovo-framework npm package, we can’t use the inline editor. We’re going to zip our project and upload it to the function.

To upload the code to Lambda, please make sure to zip the actual files inside the directory, not the HelloWorld folder itself:

Select and zip all files in the folder

Let’s go back to the AWS Developer Console and upload the zip:

Lambda Function: Upload ZIP

Now save your changes with the orange button in the upper right corner:

Lambda Function: Save

Test Your Lambda Function

Great! Your Lambda function is now created. Click “Test” right next to the “Save” button and select “Alexa Start Session” as the event template:

Lambda Function: Test

Click “Test,” aaand 🎉 it works!

Lambda Function: Test Result

Add ARN to Alexa Skill Configuration

Copy the ARN at the upper right corner:

Lambda Function: Copy ARN

Then go to the Configuration step of your Alexa Skill in the Amazon Developer Console and enter it:

Alexa Skill AWS Lambda ARN Endpoint

Great! Now it’s time to test your Skill:

6) “Hello World!”

Go to “Test” and enable your Skill for testing:

Wanna get your first “Hello World!”? You can do this by either using the Service Simulator by Alexa, test on your device, or on your phone.

a) Test Your Skill in the Service Simulator

To use the simulator simply invoke your Skill:

Alexa Skill Service Simulator

This will create a JSON request and test it with your Skill. And if you look to the right: TADA 🎉! There is your response with “Hello World!” as output speech.

b) Test Your Skill on an Alexa Enabled Device

Once the Skill is enabled to test, you can use a device like Amazon Echo or Echo Dot (which is associated with the same email address you used for the developer account) to test your Skill:

Test Alexa Skill on your device

c) Test Your Skill on Your Phone

Don’t have an Echo or Echo Dot handy, but still want to listen to Alexa’s voice while testing your Skill? You can use Reverb for that.

Test Alexa Skill on your phone with Reverb.ai

With Reverb, you can bring Alexa functionality to either your Mac or your mobile phones (iOS and Android). Go to their website by clicking the screenshot above and download it to get started.

 

Next Steps

Great job! You’ve gone through all the necessary steps to prototype your own Alexa Skill. The next challenge is to build a real Skill. For this, take a look at the Jovo Documentation to see what else you can do with our Framework:

Jovo Documentation for Alexa Skills and Google Actions