Every system needs to move with the times. Apple needed to make its MacBook thinner, lighter and faster all at the same time. Marvel had to pack more superheroes in their movies. I even hear that Wi-Fi is available on aeroplanes. Well, here at DiUS, our illustrious and sometimes infamous table tennis scoring application needed a refresh.

When we had one of our project teams working in our office using an Amazon Echo, I had an idea for a simple Alexa skill: the ability to enter table tennis scores using your voice. Skills are like voice apps for the Echo. Out of the box, there are skills to check the weather, play songs on Spotify, and catch up on your daily news briefing.

As always when I explore something new, I start with a very simple walking skeleton so that I knock out as many unknowns as possible. In this case, I wanted to build a skill that accepted a phrase like “Roger beat Rafa” and it would enter the result in our scoring application. Our table tennis scoring application exposes a REST interface that is ready to accept the input. Architecturally it would look like this:

An Alexa skill deployed to the Echo will invoke a Lambda function that will in turn invoke the REST API exposed in the table tennis application. Simple, right?

Building an Alexa Skill

To start with an Alexa skill, you need a developer account for Amazon. The Alexa skill is set up in the portal via a wizard like interface. The first thing you need to do is to define an invocation name, I called mine “pong.” You use this name to bring up the skill when interacting with the Echo, so you would say something like “Alexa, open pong.” An Alexa skill is made up of intents and utterances. Intents are essentially actions designed to achieve an outcome. We will define an intent called “TableTennis.” An intent has slots which are like parameters. So this intent will have two slots, one to hold winner and one to hold the loser.

The intent schema should look like this:

{
  "intents": [
    {
      "slots": [
        {
          "name": "Winner",
          "type": "AMAZON.US_FIRST_NAME"
        },
        {
          "name": "Loser",
          "type": "AMAZON.US_FIRST_NAME"
        }
      ],
      "intent": "TableTennis"
    }]
}

Next we need to define a “Sample Utterance” which is what someone would say to interact with the skill. In this case it’s “Winner beat Loser.” Both slot types are defined as “AMAZON.US_FIRST_NAME.” So the utterance would look like:

TableTennis {Winner} beat {Loser}

Lambda – Call me maybe

Now we need to hook the skill up to a lambda function. The lambda function will take the winner and loser slots from the Echo skill and post them to the table tennis REST API. I typically use Serverless to provide a framework around my lambda functions. Also in this case I used Alexia which is an Alexa JS framework to make responding to Alexa skills slightly nicer.

We start by defining an app in the alexia framework.

const app = alexia.createApp('TableTennis', {shouldEndSessionByDefault: true});

And then we add an intent to this app to handle the intent when it is invoked from the Echo device.

app.intent('TableTennis',  (slots, attrs, data, done) => {
    const winner = slots.Winner;
    const loser = slots.Loser;
    const options = {url: resultsUrl,
                       method: 'POST',
                       headers: {'Authorization' : 'Token ' + apiKey},
                       form: {'winner': winner, 'loser': loser}}

      setTimeout(() => {
        request(options, function(err, response, body) {
          const json = JSON.parse(body);
          const complete = 'Results entered,' + ' ' + json['message'];
          done({text: complete, end: true});
        });
      }, timeout);
    }
});

Also the table tennis REST API will respond with JSON and we take the message and send it back to the Echo so that it gets read out.

All the source code for this article can be found here.

Testing testing testing

Once the Lambda function is deployed we can start testing it. We can use the “Service Simulator” in the portal to enter sample utterances to see if the skill actually works. If that is successful, the next step is to actually try it out on an Echo. You wake up the Alexa and open the skill with the invocation name and proceed to say the utterance as per the video below.

Wrapping up

So this article has shown you how to develop a custom skill with an Echo. I hope this inspires you to think of some creative new Alexa skills to write.