Code Your First Alexa Skill in 30-ish Seconds (Using Clay). Ready? Go
In this walkthrough, I’ll guide you through everything you need to know in order to build your first Alexa Skill using Clay (full-disclosure I’m a cofounder). Clay is a layer on top of AWS Lambda & other micro-services platform that makes it much easier to get APIs & Lambda functions up and running. The goal at Clay is to take the frustrating parts out of software development (installation, configuration, debugging poorly documented errors), and make it as fluid & fun as it should be.
If you need help following this walkthrough — join our Gitter chat room and our community will help you get unstuck as you’re developing your Alexa Skills & shipping them out to the world!
You can continue to learn about Alexa Skills & what’s happening in the community by signing up for our Alexa Skills Newsletter & registering for upcoming Alexa Skills Events:
Overview of how Alexa Skills Work
In this tutorial, I’ll walk you through making the first Skill that I myself made, a service that tells gives you inspirational messages whenever you talk to it.
The basic format of how you call an Alexa Skill is as follows:
When you create a Skill, you register an “Invocation Name”, this is the trigger word that lets Alexa know that the user is trying to activate your Skill. The utterance is the phrase that follows the invocation word.
Part of what Alexa then does, with the guidance you’ll give it when you setup your skill, is translate that Utterance to some sort of user Intent.
For example, when someone says “Alexa ask AwesomeBot for some encouragement” they’re trying to invoke the GetAwesomeSaying Intent. They might also call this by saying things like:
- “Alexa ask AwesomeBot to tell me something awesome”
- “Alexa ask AwesomeBot for an awesome saying”
- “Alexa ask AwesomeBot for an emotional boost”
These are examples of different “utterances” that all map to the same user intent: GetAwesomeSaying
Create a New Alexa Skill
Ok, let’s Sign Up / Log In to the Alexa Developer Portal and make our first Skill.
After you complete the signup process you’ll find yourself in the Amazon Developer Dashboard, and you’ll want to just head over to the Alexa section of the dashboard, and select the Alexa Skills Kit option.
Alright, now we’re in the Alexa Skill creation wizard, let’s walk through the steps.
Skill Information
Here we’re going to select a Custom Interaction Model, and choose the Name & Invocation Name for the Skill. The invocation name is the keyword that users will use to trigger your skill, in our example, it’s AwesomeBot:
“ Alexa ask AwesomeBot to give me an awesome saying”
In the Global Fields section, you can see an Alexa Skill also has the ability to stream audio, which is useful for building things like a Podcast player. That’s beyond the scope of this tutorial, but there’ll be a follow up post specifically on that topic. For now mark the Audio Player field as No.
Design Your Interaction Model (Intents & Utterances)
In this step, we’ll give Alexa information about how our skill is commonly invoked by users. Our Skill might be able to do a few different things, so let’s say our Alexa Skill, Awesome Bot, can do 2 different things:
(1) It can tell us an awesome saying that boosts our confidence
(2) It can tell us an awesome random lucky number
In this case, we can say that there are 2 Intents for our Skill to handle.
GetAwesomeSaying
GetAwesomeNumber
Intent Schema
Copy and paste this into the Intents configuration pane
{
"intents": [
{
"intent": "GetAwesomeSaying"
},
{
"intent": "GetAwesomeNumber"
}
]
}It should look like this:
Custom Slot Types
We won’t go through these in this tutorial, but slots are used to handle user submitted variable. For example, in an upcoming tutorial we’ll go through building a Skill that lets you check if a food is Paleo & Whole30 — to build this skill we’ll need to have a slot in our Intent, where the user can say what food they want to check — e.g. “Ask PaleoBot if [FoodName] is paleo”
Utterances
The next thing we’ll need to do, is to give Alexa some example of the types of things a user might commonly say to invoke these intents. This is essentially a way to map an Intent to a sample utterance. The f
Intent SAMPLE UTTERANCELet’s go ahead and copy the below utterances so that the utterances section of the page looks like below. As you can see, we’re matching a variety of sample utterances to the Intents we setup in the preceding section.
GetAwesomeSaying to tell me something awesome
GetAwesomeSaying to give me an awesome saying
GetAwesomeSaying to give me some encouragement
GetAwesomeSaying for an awesome saying
GetAwesomeSaying for an emotional boost
GetAwesomeNumber to tell me an awesome number
GetAwesomeNumber to give me an awesome number
GetAwesomeNumber to give me a number
Coding the Skill
Now we need to write the code that will handle the Skill Intents. Click next to get to the configuration. As you’ll see this page gives you two options for how to code your Alexa Skills: as code running at some HTTPS endpoint, or as an AWS Lambda (a service that Amazon provides which lets you host & run event-triggered functions within the AWS ecosystem).
Actually working with AWS Lambda is pretty annoying & getting an HTTPS endpoint up and running can be a bit of a headache, but Clay makes the process of getting a code function up and running at an HTTPS endpoint trivial. To publish your Skill, your HTTPS code needs to also verify that the requests are coming from a valid Alexa, which is done by verifying a signature in the header — but don’t worry Clay also takes care of handling the Alexa specific verification for you, so you can just focus on writing the actual code. The best part is that under the hood that code is actually running as an AWS Lambda. For today, we’ll set up our service to run at an HTTPS endpoint powered by Clay.
At the end of the day, when a user speaks to Alexa and invokes your skill, Alexa parses what it thinks the user’s intent was, and then sends a JSON request with the intent to the endpoint/lambda function you specified, in our case the Clay function we’ll create. The code in that function is then responsible for writing handlers for each of the intents & responding with a JSON object in the Request format that Alexa expects — but don’t worry, all of this is made much easier by the various client libraries that are available for parsing & handling Alexa Requests & Responses.
Create a New Clay Alexa Skill Function
If you haven’t yet installed / signed up for Clay let’s quickly do that from your Terminal.
npm install -g clay-run
clay signupThe beauty of Clay, is that it lets you get a function up and running at an HTTPS endpoint with a single command in your Terminal: clay new . You can spin up functions with different types of templates — in our case we want an alexa-skill template, which just saves us time in the initial setup. We want our function to be called awesome-bot (doesn’t really matter what you call it, but let’s go with that for now). Navigate to a folder where you want the code for your function to live and invoke the following command:
clay new awesome-bot --template alexaSo here we created a new function on Clay, which is running at the HTTPS endpoint you see in the output. This command also created a folder in your directory with the name awesome-bot, where the code for the function lives. In our case, the code is setup for the purposes of easily coding an Alexa skill.
Copy Clay Function HTTPS Endpoint Into Configuration
Let’s go ahead and paste the link to the HTTPS endpoint we just created on Clay into the Alexa configuration page. For example, mine was:
Then hit Next to get to the SSL Certificate.
Note: You’ll likely have noticed the Account Linking section at the bottom of the Configuration step. Account linking allows users to create accounts or login to existing accounts with your service. We’ll be going through that functionality in a later tutorial, for now we want to get you setup for the basics.
SSL Certificate Settings
One of the big benefits of using Clay is that we take care of all the concerns around SSL certificates when using HTTPS. Select the first option in the SSL certificates page
Test
Since the template function is already instrumented to handle the intents we specified in the awesome-bot Alexa skill, we can go ahead and actually test our function.
There are 4 different ways that we can test out our Skill.
Try It Out By Speaking To Your Alexa
If you have an Alexa handy nearby you can try out the awesome-bot skill right away. Just first make sure that the Alexa Skills Dashboard testing pane has the toggle set to Enabled “This skill is enabled for testing on your account” as seen above. Then just try one of the utterances we set up:
“Alexa ask Awesome Bot to tell me something awesome”
Here’s me giving the Awesome Bot a test run:
Testing Using the Amazon Voice & Service Simulator
Amazon provides two alternative ways to test your skill via their interface.
The Voice Simulator lets you simulate what it sounds when Alexa says certain things. This can be particularly handy for setting up your SSML, which stands for Speech Synthesis Markup Language. SSML let’s you modify how Alexa sounds when she responds.
Further down the page, The Service Simulator, let’s you type in a sample utterance to your Skill to see how it responds. This allows you to see the format of the JSON that Alexa sends as a request, and a typical format of the JSON it expects as a response. As you’ll see, in our code the Alexa Skills SDK takes care of the parsing of the Alexa request, and the preparation of the Service response. Here are the docs if you do want to dive deeper into the Request & Response Object formats:
🙌 💻 Let’s Explore & Tweak The Code
Ok, now that you know how to test the skill, let’s start exploring the code that powers the awesome-bot skill and see what’s happening under the hood.
The clay new command created a folder that hosts the code for your function. If you called your function awesome-bot, as in our example, then you should have an awesome-bot folder in the directory where you called the function.
Open up the directory in your editor of choice & let’s take a look.
A clay function is like a node environment, you can install whatever packages you want using the standard package.json & npm install.
📦 package.json
We’ve already installed the one dependency which is the clay-alexa-sdk, which is just a fork of the alexa-sdk provided by Amazon, but tweaked to respond over HTTPS rather than as a Lambda.
⚡️ awesome-bot.js
The file for your function is eponymously named awesome-bot.js, that’s where you’ll be writing your actual code. Let’s break up what’s happening in that file piece by piece quickly.
Here’s an annotated source for awesome-bot.js that may help with the walk through. One thing to note in the source code is that we also handle the ‘Launch’ Intent. The Launch intent is what happens when someone activates the skill with the general launch words like “Alexa open Awesome Bot”. In our case, the Launch Intent just j
↓ Link below has nicely commented awesome-bot.js code ↓Also, here’s a link to the clay-alexa-sdk which has instructions on setting up your handlers!
Tweak & Deploy Your Code in Seconds
Go ahead and try making a change to what awesome-bot does, perhaps add a handler for another Intent, or modify how Alexa responds to the existing intents. Then, to get your code live at your HTTPS endpoint again just call
clay deployOnce you do this, the updated function code for awesome-bot.js should be up & running at the endpoint! Give your Alexa skill another test to make sure it’s running well.
Getting Your Skill Ready for Publishing
The final step is to submit your Skill to the Alexa app store. If you publish a skill before January 31st you’ll even get a free Alexa sweater:
https://developer.amazon.com/alexa-skills-kit/alexa-developer-skill-promotion
Ok, so in order to publish, as with other app stores, we need to just enter a bit of info describing our skill. You can see what I’ve entered for Awesome Bot.
For tips on what kind of testing you should do before submitting check out this guide:
The Amazon certification process is still a little bit murky as we’ve heard from other Skill developers in the community. We’ll be doing a round up of best practices we’ve heard in an upcoming post.
Why Use Clay & Other Options for Creating Alexa Skills
I thought I’d take two seconds to just go through why we think Clay is helpful even in this early stage for helping you get a Skill up & running. We’ve tried the alternatives, and we still found them to require too much configuration. For people who have used AWS interfaces before you know you can likely expect a headache. With other frameworks there’s a lot of configuration whereas we tend to sane-defaults — convention first, configuration later. We wanted to make it as instant as possible. Here are a few alternatives to getting Alexa Skills set up in other ways if you want to check them out:
Code a Lambda directly on AWS Uploading Zip Files
- My friend Brain Donahue has a great intro on how to get started spinning up a Lambda with AWS:
- https://medium.com/@bthdonohue/build-your-first-alexa-skill-8a37dc3103d6
- Cons: Setting up your AWS Lambda requires you to Zip files locally to deploy :S & the Lambda & CloudWatch Logs interfaces are slightly frustrating to use
Use a Framework like Apex or Serverless to Deploy
- Apex & serverless.com are good abstractions on top of AWS Lambda, helping with the deployment and configuration process. We recommend checking them out , but we think clay can be helpful since these frameworks still require you to know about about IAM policies & make more choices than we think you should have to in order to get going actually publishing Alexa skills
What’s Next?
Join Our Gitter Room to tell us what you built or are trying to build & how we can be helpful!
Clay is great for more than just Alexa skills — it‘s the perfect solution for building . You could try to build an Amazon Dash Button, a Backend for Your Application, a Web Scraping service. No matter what you’re working on — we’re here to help, just ping us in the Gitter!
Here are some more great resources for Alexa as well:
- Great Slack focused on Alexa development. Found it to be a helpful community so far: http://www.alexaslack.com/
We’re just starting off learning Alexa just like you, so over the next little while, as we dive in, we’ll document & share out what we’ve learned. Here’s a few things we’ll be exploring in the coming weeks:
- Alexa Skill that takes in a user specified food, and reads from a database to tell you if a specific food is Paleo, Whole30 or neither
- Alexa Skills that saves reminders to a database and let’s you access them again.
- Alexa Skills that hits an API service
- Alexa Skill that plays audio files
- Alexa Skill that uses authorization to check your bank balances
Cheers,
Nicolae & The Clay Team
Nicolae is a cofounder at Clay, working on building well-designed tools for creating software for new mediums.
