January 14, 2017
Chris Power
After another influx of Alexa powered devices made their way into consumer homes, many companies hope to create custom skills. We’ve had the opportunity to help integrate custom business logic that will keep our clients top of mind, and you can too.
The Amazon documentation is very straightforward, so we made a tutorial to help create custom skills that involve linking your user’s Amazon account with their profile on your application.
Throughout this article, you will learn the process of creating a custom skill, linking it with a user in a Rails application (using Devise and Doorkeeper), and querying data on the user’s behalf.
If that sounds like fun, let’s get started!
I have had the pleasure of working with the premiere Pokemon hotness rating application on the Internet today. It’s very disruptive. Thankfully, this author was kind enough to let me use their application as an example of writing custom Alexa skills. This is a basic application that allows a user to sign in, vote on the hottest Pokemon, and see the results.
For our Alexa skill, we will enable a user to:
All by using their voice!
Sign up for a developer account on Amazon, click on the Alexa Tab, then Alexa Skills Kit. Once in the Alexa skills dashboard, click on the “Add a new Skill” button.
Let’s go through the new skill sections one-by-one.
Skill Information: This is where you put basic info like your skill name, invocation name, etc. All we do here is put “Pokemon Hot or Not” for skill name, and “Pokemon hot” for the invocation name.
Note: the invocation name is what users say to ask questions through your skill.
Interaction Model: Place your “Intent Schema” and your “Sample Utterances” here. In short, your Intent Schema is the list of intents you want for your skill. An “Intent” is basically a question. We are going to keep this part simple with only a couple intents. For more information on intents, see this section of the Alexa documentation. We will also add some sample utterances on this page. An utterance is an example of how your user can ask a question. You will generally want a lot of sample utterances in your skill.
Let’s leave the rest of the skill configuration blank for now. We’ll come back to the configuration after we’ve set up our application to talk to Amazon. For now, take a break, grab a coffee, and rest up. You’ve done a lot.
Let’s set up our application to handle Alexa’s requests. For this section, we’re going to assume you have a Rails API available.
Create a new controller for requests from Alexa
In this controller, you’ll note that I return an odd piece of JSON. A lot of this is boilerplate you need for Amazon. The most important part is the “outputSpeech” section. Here is the documentation to learn more about responses and requests from Amazon. For now, we’ll stub out a simple response “hello from Pokemon Hot!”
and update your routes file
Once you’re finished make sure to restart your Rails server.
Install ngrok for SSL locally
ngrok will host a local version of our ap, and allow Amazon servers to speak to it. Amazon requires our server to have SSL. We don’t want to host a heroku SSL instance simply for testing, so ngrok will work perfectly.
After installing ngrok, set it to run on whatever port you’re running your Rails server on. In our case, it’s good ol’ port 3000.
After running this command, you should see something like this:
Do you see that https link above? That is what we’ll tell Alexa to communicate with.
Get Alexa to talk to us
Now that we have:
Let’s point Alexa at our application. Go to the Alexa skill you created earlier, click on “configuration” tab, and paste in the https link from ngrok, including the route we created:
Now let’s test!
Go to the “Test” tab in your Alexa skill, and type in an utterance. If you did everything correctly, you should see output similar to below:
Great Job! You see we got a response back from our API. You can even hear Alexa say it out loud by clicking the “Listen” button. This is another great opportunity to take a break. We’ll finish this up when you get back!
This is where things get very interesting. We have the building blocks in place currently, and now it’s time to finalize everything. We are going to focus on a few major things from here on out:
Install and configure Doorkeeper
Doorkeeper is a great gem that allows you to introduce OAuth 2 provider functionality to your Rails application. Let’s install and configure Doorkeeper.
Then generate migrations and boilerplate Doorkeeper stuff:
Then make sure Doorkeeper added routes to your app:
Configure Doorkeeper to use the current_user in resource_owner_authenticator. Since we use Devise, this is handled easily:
For our purpose, we’re going to use “implicit grant” for OAuth. Configure that in Doorkeeper config again:
Create an OAuth application in Doorkeeper to handle the Amazon requests
For the “redirect URIs”, go to your Amazon developer account, click on “Configuration” in your custom skill, then click “Yes” for account linking.
Next, go back to Doorkeeper and finish your new application
After hitting “Submit” you should have an application for Amazon to connect to!
Let’s test this out
Restart your server and “Authorize” the app with Amazon.
If you don’t already have an Alexa account, create one with the same email as your developer account. Then, go to alexa.amazon.com, click on ‘home’ and click ‘Your skills’ at the top right. You should see your custom skill listed there. Click on it and authorize:
Awesome! We’re almost there!
Protect controller with Doorkeeper
First things first, let’s protect the controller with Doorkeeper. We’re going to add a few methods that I will explain shortly.
Actually get user data for responses
We are just about done! Now let’s grab information from the actual database and return it to the user depending on what they asked our app for. If you remember, we have two intents to handle “HottestPokemon” and “LastPokemonVote”.
The final code should look like this
If you’d like to see the demo app used in this post, check it out here
This tutorial scratches the surface of what is possible with an open platform like Alexa. Although this demo showcases simple responses, you can build complex interactions that span multiple skills. Contact us if you have an idea for a custom skill you would like to integrate for your business.
