Creating an Alexa Skill in 2021
Although I appreciate tech gadgets, it took me until now to get an alexa for my home and as a hobby developer I was interested in the possibilities of writing an Alexa skill. While looking for tutorials, I found that there’s quite a lot of information on the web, but it’s either outdated or way too detailed for a beginner who wants to start quickly. In this tutorial I want to give you a basic introduction how Alexa skills work , what to mention and what need in order to create your first skill. At the bottom I summed up a few tipps and tricks you might find handy as beginner.
Structure of a voice command
At first it is important to understand how a voice command is interpreted by Alexa. It consists of four parts:
- Wake word (“Alexa”)
- Invocation name (name of your skill)
- Utterance (certain words that lead to specific actions)
- Slots (optional variables)
If you wake Alexa, it will listen to the complete sentence you say and separate it in the invocation name, the utterance and optional variables (“slots”).
The invocation/skill name can be chosen by yourself at the beginning of creating your skill, so keep that in mind when choosing an appropriate name.
The utterance describes one or more keywords and what action should be triggered when they are said. For example, if you say “Alexa, ask skill name to say my name”, the utterance would be “to say my name”. Depending on the utterances we are going to define, different functions will be called.
Creating your skill
Now that you know this, we will try to develop an example skill that has two features:
- Say your name (which we predefine)
- Repeat a name we tell alexa
The Developer Console
Head over to the Alexa Developer Console and (if not already done) sign up with them. Click on “Create skill” and choose a a name for it. For demonstration purposes I’m going to use name sayer. Enter the desired skill name and leave everything else empty. Leave the model at “Custom” and the hosting method at “Alexa-hosted (Nodejs)”. You can also select python, but I’m going to cover the Node.js-version in this tutorial.
By the way, be careful which hosting region is selected in the upper right corner. This (usually) determines where your log files will be saved.
On the next page, choose “Start from scratch” and continue with the template.
You will now find yourself in the skill section of the developer console, which can be quite confusing at first. We’ll hold onto the checklist on the right and start with configuring our intents.
In the beginning you will only find the HelloWorldIntent which comes with the template.
The built-in intents are provided by Alexa and called in case of errors or if the users says “help” so that you don’t have to deal with these common things yourself. We won’t change them by now.
Now click on Intents → Create custom intent and create an intent called SayMyNameIntent. You will be redirected to the utterances page where you can now define which keywords should trigger this intent. Add phrases like “say my name”, “say name”, “what’s my name”, “how am I called” and others you might like. When you are finished, click Save Model in the upper region.
Next, we create the RepeatNameIntent using the same steps as before. Because we are going to repeat a name the user said, we have to configure a parameter (“slot”) for this intent. On the utterance page of the intent you just created, add a new slot in the bottom section and name it nameToRepeat. You can select from a large variety of data types as slot type, e.g. numbers, dates. For now, select Amazon.SearchQuery.
Now that you defined this slot, you can use it directly in your utterances. Use curly brackets {} to insert the parameter like shown in the image. A colored background signals you that any input followed by your keyword will be considered as the desired parameter. If you say “repeat the name Peter”, Peter will be used as slot value in your function. The slot can be positioned anywhere.
We need the slot to be required to fulfill the intent. To mark the slot as obligatory, you have to click on the slot nameToRepeat and activate the checkbox in the “slot filling”-section.
When the user says one of the phrases containing the name to repeat directly, Alexa will process it as slot value. If not, it will ask the user with a message you can define.
Since we are all done here, click Save Model and Build Model.
Coding the logic
The setup preparations are finished and we can start coding. If you are familiar with Nodejs, you’ll have an advantage for sure. In the top navigation bar, click on Code and you are redirected to the index.js file. In this tutorial, this is the only file we’ll need.
Every intent we defined previously needs a separate handler in our code block. The template created two handlers for us which are already implemented: LaunchRequestHandler and HelloWorldIntentHandler.
LaunchRequestHandler is predefined and called whenever you say “Alexa, open name sayer” without giving any more information.
HelloWorldIntentHandler is a sample function we won’t need, but have a look at in order to analyze what happens.
The canHandle-method checks if a request is started and if the request type is HelloWorldIntent. Which intent is triggered depends on the utterances we defined earlier. If the user says “hello”, “how are you” and so on, this handler will be triggered (this was set by the template).
The handle-method defines what actions should be done when the intent is triggered. In this case it only prompts “Hello world”.
Because the structure of all handlers is always the same we just copy the whole function and adapt it to our needs:
We define a handler for the intent named SayMyNameIntent. It’s good practice to name the handler according to the name of the intent.
Lastly, you need to add the name of the handler SayMyNameIntentHandler to the requestHandlers on the bottom of the file so that the skill knows it’s there.
Now the functionality is connected and Alexa knows that it has to call SayMyNameIntentHandler when the user uses one of the defined utterances.
Working with slots
Let’s start implementing our RepeatMyNameIntent and find out how slots work. Copy the previously created handler and rename it to RepeatMyNameIntentHandler. Don’t forget to add it to the requestHandler-section.
We defined a few utterances which trigger this intent like “repeat name” or “repeat the name {nameToRepeat}”. So we have two situations:
- The user tells Alexa to repeat a name without specifying which. In this case, Alexa has to ask for the name
- The user tells Alexa immediately to repeat a specific name. In this case, Alexa parses the slot and reacts directly.
The Alexa SDK provides a comfortable way to get the parameters of an input. Let’s have a look:
Using Alexa.getSlotValue() we obtain the content of the slot. Since we defined nameToRepeat as obligatory slot in the build section, Alexa will ask for it until you tell it or cancel. If you wait too long or give an invalid answer, Alexa will reprompt a text.
Skill testing
Since we are done for now, click Save and Deploy in the menu. You can now head to the Test section in the upper menu band and change the skill testing enabled to Development. Alexa provides a simulator so that you can test the behaviour of your skill in different situations.
Congratulations, you developed your first Alexa skill! You can download the complete file contents on the Github repo.
Tips and tricks
During developing my skill I experienced a few problems that cost me quite a lot of time. Maybe you can avoid these and save some time with the following tips.
Have a look at the json output
When testing your skill, all input and output is printed in json format. This information can be extremely useful during debugging, as it also shows the complete request content such as intent and slots.
"request": {
"type": "IntentRequest",
"requestId": "amzn1.echo-api.request.8d3ed5dc-4d8f-460e-9480-d932c465211f",
"locale": "de-DE",
"timestamp": "2021-04-22T16:22:48Z",
"intent": {
"name": "RepeatNameIntent",
"confirmationStatus": "NONE",
"slots": {
"nameToRepeat": {
"name": "nameToRepeat",
"value": "martin",
"confirmationStatus": "NONE",
"source": "USER"
}
}
},Debug using console.log()
Sometimes the json output is not enough our you just get a generic error while testing like “something went wrong” or “an error occured” without giving you specific information. Use console.log() to track your progress, position and variables. To see your log files, click on CloudWatch Logs.
You can’t find your log files
Although logging everything is a great way to debug, I just could not find the log output in the CloudWatch log console. Errors like “Protocol group does not exist” occured and none of the buttons lead to the appropiate log group.
If you experience the same, your logs are probably saved on another location than you skill. You can then either browse through the different regions in the CloudWatch Console or click on the little arrow next to CloudWatch Logs in the code section. If you don’t find them in the default location, they might be saved in the others.
You know you are in the right location when you find a log entry with current date in your log streams.
Develop offline as long as possible
If you’re trying to find an error in your skill, it can be painful to do console.log() and switch between code and log section all the time. Alternatively, you could develop and test the core functionality of your skill in an offline Nodejs environment. Just install Nodejs on your local computer and create a local .js-file which you can run using the command node index.js.
If you run this code and open https://localhost:3000 in your browser, it will execute the content which makes it a charm to debug your code.
Save time using the utterance evaluation
Sometimes you keep on coding in circles although the code logic is correct. Instead, there might be a problem with your utterances. Alexa offers an utterance evaluation function which makes it easy to test different variations of inputs. As a result, you’ll see which utterances trigger which intents and which slot values are detected.
Final Words
Developing an Alexa skill has become quite easy if you know these fundamentals. This tutorial is supposed to give you a quick and easy introduction and was therefore pretty basic.
Because skill development is based on NodeJS, you can add any dependency of your choice and (for instance) connect APIs or implement more complex functions. I hope this tutorial helped you out a bit.