Alexa Skills Kit (ASK) Development Tutorial

Emir Ercan Ayar edited this page Aug 11, 2017 · 22 revisions

Welcome to the Alexa Skills Kit (ASK) development tutorial.

This wiki aims to describe how to develop Alexa Skills with several languages. I'll point sample custom skills I've made and also Alexa's official tutorials. You also see my learning path with skill repos I've shared.

Let's start.

Step 0: Learn how things work

First, have a look at how Alexa custom skills work. If we summarize the flow;

  • Create an Alexa Skill on Alexa developer portal
  • Define essential details about your skill, on Skill Information tab, like
    • Skill name: will appear on Alexa Skill Store
    • Invocation name: user (or just you?) will use this word to start the skill
    • Essential config like defining the skill as a video skill or an audio skill.
  • Define your skill's interaction model on Interaction Model tab: Basically, teach to Alexa that your dialog flow. Which words match to main roles of your skill, which of the words are just parameters, which are just changeable or unnecessary.
  • Config your skill's service enpoints and authorization on Configuration tab: Will it connect to your HTTPS enpoint or an Amazon Lambda function. Also, will it use account linking? (We'll talk about linked account skills later, but here is a tip; will your app post tweets from the same account if it has a capability to tweet? So, you need to authenticate your skill user to do something with their own accounts.)
  • Prepare your skill's software which send JSON responses to JSON requests comes from Alexa skill. Every time you use your skill, an JSON request comes to your Alexa Skill and waits a response immediately. Async is not possible. (for now at least) This JSON format is defined by Amazon and they're very strict about it. If you want to certificate your skill and publish on Alexa Skills Store, this'll be your headache.

You've heard some new concepts. Have a look at this quick tutorial from Amazon and get your hands dirty to be familiar with these concepts; Start building for voice with Alexa

You'll see intentSchema.json and Utterances.txt files in every alexa skill repo I've shared. These contain Intent Schama and Example Utterances data which you need to define in Alexa development portal. You can understand what the skill does exactly by just reading these two files.

Step 1: Simple Exchange Calculator Skill with Nodejs

Repo: eercanayar/alexa-skill-exchange-calculator

This was my first Alexa Skill. Just think like a Hello World thing. I aimed to see what happens when you connect a HTTP endpoint and retrieve data from there in the Alexa skill. Shortly, it calculates EUR/USD to TRY exchange of your input to Alexa.

calculateExchange exchange {Amount} {Currency} 
calculateExchange calculate {Amount} {Currency} 
calculateExchange convert {Amount} {Currency} 

This skill uses hard coded JSON input and outputs. So, there is no alexa-sdk here. I've realized later that this is legacy, noone recommends it. You can't pass Alexa Certifications with non-alexa-sdk code. Somehow, I found this as an example from old tutorials. It works well, but continue with alexa-sdk just like me.

Step 2: Simple Exchange Calculator Skill with NodeJs + Alexa-SDK

Repo: eercanayar/alexa-skill-exchange-calculator-sdk

This is the alexa-sdk version of previous skill. There is lots of advantages of using alexa-sdk to handle json requests-reponses. The most important of them is debugging. Maybe you have noticed that you're uploading your code to Amazon Lambda with a zip file and done. You can just see console logs and outputs after runtime. But debugging is vital because we'll not develop just simple exchange calculator apps. Follow this cool tutorial to debug your code from remote with Visual Studio Code. Simply, you'll authorize your Amazon account on your development environment, put your input.json which copied from Alexa developer portal's Test section and debug it.

Utterances and Intent Schemas are same, because this is the same skill as I said.

Step 3: Exchange Calculator Skill with NodeJs + Alexa-SDK + Account Linking with Twitter

Repo: eercanayar/alexa-skill-linked-account-twitter-nodejs

We're going one step further: sharing the exchange calculation result as a tweet. I've selected Twitter because it'll be an oauth implementation. Thus, I can re-use this with little modification later, if I need. Please don't ask that why are we tweeting exchange calculations, we're just improving our alexa skills here.

calculateExchange exchange {Amount} {Currency}
calculateExchange calculate {Amount} {Currency}
calculateExchange convert {Amount} {Currency}
tweetResult tweet it
tweetResult tweet

You can read more about how to link accounts with alexa but here is the hint; linking between twitter and alexa without using any middleware is not possible. If you're trying to link alexa with your own service/web site, it'll be also fail. The point is differentiation of implementing oauth. This is really huge topic and if you go deep to research about it, you can be lost on the web. As a summary, -almost- every oauth provider wants different parameters and variables during authentication flow. So you need to develop a middleware to do mediatorship between alexa and twitter's oauth services. The solution is adapting twitter & alexa API's by developing a middleware which integrates alexa skill user with twitter api. it moves requests access tokens, passes amazon's required parameters.

Here is my middleware to solve this, nodejs + express, heroku-ready.

Repo: eercanayar/alexa-skill-linked-account-twitter-middleware

On Alexa developer console, you need to set Authorization URL as as account linking configuration and do not forget to define env variables on heroku dashboard.

  • holds amazon's required parameters on session,
  • performs standard oauth requests to obtain key & secret
  • no database. returns token and secret in "TOKEN,SECRET" format to amazon alexa.

Note to myself: I've developed this on heroku to save time. But I'll do the same with Amazon Lambda + API Gateways. It's better if all of the solution lives on same environment; Amazon.

Step 3-EX: Exchange Calculator Skill with C# .NET Core + Alexa-SDK + Account Linking with Twitter

Repo: eercanayar/alexa-skill-linked-account-twitter-dotnet-core

I've developed the same skill with C# .NET Core 1.0 to see how things going with .NET Alexa-SDK. Also it's good to see deploying C# code directly from Visual Studio to Amazon Lambda without uploading zip file from Lambda console. Microsoft is going well. By the way, I used alexa-csharp-lambda-sample repo as cheat sheet.

Step 4: More IoTing; Alexa Skill - Thingworx Integration

Repo: eercanayar/alexa-skill-thingworx-basic

Assume that you have an IoT ecosystem already (We have.) and you want to get data via Amazon Alexa. This is an sample alexa skill which can reply your questions using thingworx services like asking temperature, humidity. Getting data from thingworx is simply a couple of HTTPS requests but getting thingworx parameters from user and defining a new dialog flow make this skill different from others.

getParameter how is the {parameter}
getParameter tell the {parameter}

I've used a simple nodejs + express + bootstrap middleware which can work on heroku to link user's thingworx parameters.

Repo: eercanayar/alexa-skill-thingworx-basic-middleware

If you're following this tutorial's steps from zero, you know how things going for account linking.

Step 5-Final: Complete Integration with Alexa, Thingworx and Twitter

Repo: eercanayar/alexa-skill-thingworx-integration

This repo contains my last combined work about alexa skills, account linking and integration with IoT ecosystems.

Assume that you have an IoT ecosystem which works on thingworx platform: Couple of sensors like temperature and humidity can be monitored on thingworx thing properties. Some smart home functions like turn on/off lights, start/stop music can be operated by thingworx services. Also there is a security cam connected to same network.

The skill provides a case study to perform this features;

  • Linking thingworx and twitter accounts from Alexa App
  • Tell sensor measurements like temperature and humidity on Alexa
  • Tweet these sensor values to linked twitter account
  • Turn on/off lights, start/stop music, enable/disable security from Alexa
  • Taking photo from security cam and sharing it on Twitter when asked from Alexa
getParameter how is the {parameter}
getParameter tell the {parameter}
serviceMusic {musicAction} music
serviceMusic music {musicAction}
serviceArm {armAction} security
serviceArm security {armAction}
serviceTurn lights {turnAction}
serviceTurn {turnAction} lights
tweetResult tweet it
tweetResult tweet
tweetParameter tweet the {parameter}
tweetParameter share the {parameter}
tweetParameter share the {parameter} on twitter
tweetPhoto tweet security cam
tweetPhoto tweet cam
tweetPhoto take cam photo

Have a look that what the repo contains:

  • lambda: Amazon Lambda function of the skill. Can be debugged on Visual Studio Code.
  • alexa-skill: Alexa skill's interaction model. Can be set on Alexa Developer Console. This has a lot of massy code, I know. I've commited this right after I see it works. I'll update it with more re-usable code.
  • account-linking-middleware: Middleware to set thingworx parameters and link Twitter account on Alexa app. Can run on heroku.
  • remote-service-client: The role about the camera was taking photo from it and send to Alexa skill to share on Twitter when requested. Notice that camera isn't on internet. It's accessible from a local IP. This remote service makes all possible. It scans IP ranges to find the current IP of the camera. Then, waits for the service call from thingworx. This C# .NET solution is based on Thingworx SDK.

eercan @Accenture Istanbul

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.