Application Integration

Host Your Alexa Skill Service on AMPLIFY using API Builder, Part 1

Amazon Alexa Skills are comprised of two components, the Amazon Alexa Skill Interface hosted on Amazon and the Skill Service, which can be hosted on any web server. Amazon typically promotes its Lambda service for hosting your Skill Service, but any web server can be used.

The Skill Interface handles the following:

  1. Speech recognition to understand what you said
  2. Parsing your speech request into an http POST to the Skill Implementation
  3. Receiving the response from the Skill Implementation
  4. Synthesizing the speech associated with the response

The Skill Service is responsible for implementing the logic associated with your speech request (e.g. fetching the weather from a weather API) and constructing a response to the POST.

In this blog post, we describe how you can use AMPLIFY to host your Amazon Alexa Skill Service. We also cover the basic setup and workflow. In future posts, we’ll explain how other aspects and features of AMPLIFY can be used as part of your Skill Service.

Background

There are plenty of resources for getting started with Alexa. Here are some that I found useful:

  1. Coding the Amazon Echo (Alexa) – How to create custom Alexa skills from scratch with AWS Lambda YouTube Video (Free)
    • This is a great soup to nuts walkthrough of a non-trivial (but simple) Alexa skill
    • Code is available here
  2. Developing Alexa Skills by Big Nerd Ranch online training videos
  3. Alexa Development For Absolute Beginners Udemy online training video (Fee)

This blog post is not focused on building skills but more on the basic structure and how you can build a framework for creating Alexa skills that are hosted on AMPLIFY using API Builder. It is intended for those who have some familiarity with creating Alexa Skills as well as those who have some familiarity with API Builder.

The concepts implemented in this example are derived from an excellent tutorial by Jordan Kasper, titled Building an Amazon Alexa Skill with Node.js.

Here are the basic steps:

  1. Define your Skill Interface on the Amazon Developer portal
  2. Add a custom API to your API Builder Project that will
    • Handle the request (a POST from the Skill Interface)
    • Construct a JSON object response of a certain structure
  3. Configure your Skill Interface to point to the URL of your custom API

Since the POST will be coming from Amazon, I found it useful to develop my API Builder project in the cloud so it would be easily accessible from the internet. This blog post discusses using Cloud9 for API Builder development.

Host Your Alexa Skill Service on AMPLIFY using API Builder, Part 1

Skill Interface

My Skill Interface is simple and enables the user to say “Alexa, ask Hello Arrow to say hi”. The Intent Schema is below:


{
  "intents": [
    {
      "intent": "HelloArrowIntent"
    }
  ]
}

The Sample Utterances are below:


HelloArrowIntent say hello
HelloArrowIntent say hello world
HelloArrowIntent hello
HelloArrowIntent say hi
HelloArrowIntent say hi world
HelloArrowIntent hi
HelloArrowIntent how are you

During development and testing, my API Builder project was running on Cloud9 so, in the Skill Interface Configuration tab, I set the Endpoint to:


https://arrowclouddev-lbrenman.c9users.io/api/alexaapphandler

When I published my project, I changed the Endpoint to my published API at:


https://.cloudapp-enterprise.appcelerator.com/api/alexaapphandler

The Skill Interface setup is shown via screen shots at the end of this post.

Custom API

According to Jordan’s Tutorial the API request coming from the Skill Interface will be a POST whose body has the following structure:


{
    "session": { ... },
    "request": { ... },
    "version": "1.0"
}

and the response should have the following structure:


{
    "version": "1.0",
    "sessionAttributes": { /* Any data you want to persist... */ },
    "response": { /* What Alexa should do... */ }
}

During my Alexa development, I found that another object, context, is present when the Echo sends the request versus when the Skill Interface simulator does, so I found the structure to actually be:


{
    "version": "1.0",
    "sessionAttributes": { /* Any data you want to persist... */ },
    "response": { /* What Alexa should do... */ },
    "context": {}
}

One way to implement this in API Builder is to create a Custom API that will service the request from the Amazon Alexa Skill Service. My Custom API, alexaapphandler.js, is shown below:


var Arrow = require('arrow');
var AlexaAppHandler = Arrow.API.extend({
    group: 'alexa',
    path: '/api/alexaapphandler',
    method: 'POST',
    description: 'this is an api that shows how to handle requests from the Alexa Skill Voice server',
    parameters: {
        version: {description:'version'},
        session: {description:'session'},
        context: {description:'context', optional: true},
        request: {description:'request'}
    },
    action: function (req, resp, next) {
        console.log('AlexaAppHandler called');
        resp.response.status(200);
        resp.send({
          "version": "1.0",
          "response": {
            "shouldEndSession": true,
            "outputSpeech": {
              "type": "PlainText",
              "text": "Hello Arrow"
            }
          }
        });
        next();
    }
});
module.exports = AlexaAppHandler;

alexaapphandler.js should be placed in your API Builder project’s /apis folder.

Let’s break down this API Builder Custom API code:

  1. Since we need to support a POST, we declare the method to be POST.
  2. The parameters: version, session, request and context were described above. Since context is optional and will not always be passed in with the POST we set optional to true.
  3. I create an appropriate response that matches the JSON structure described above:
    
    {
        "version": "1.0",
        "response": {
            "shouldEndSession": true,
            "outputSpeech": {
                "type": "PlainText",
                "text": "Hello Arrow"
            }
        }
    }
    

    Note that sessionAttributes is not included in my response since I am not persisting any data between voice requests.

Once the API Builder project is published change the Skill Interface Configuration Endpoint to the published API:


https://.cloudapp-enterprise.appcelerator.com/api/alexaapphandler

This Skill Implementation will cause Alexa to respond with “Hello Arrow”. You can hear the dialog here.

Conclusion

You can see how easy API Builder makes it to define an API that can help you create your Alexa Skill Service.

While the code above works fine in the simulator and on a physical Echo device, it will probably not pass Alexa Skill Certification since we are not verifying the request to insure that it is coming from the Amazon Alexa Skill Interface. This is mentioned and described in Jordan’s Tutorial.

We’ll cover ‘verifying the request’ as well as how we can leverage other features of AMPLIFY, such as ArrowDB, in future blog posts.

Skill Interface Screen Shots

Host Your Alexa Skill Service on AMPLIFY using API Builder, Part 1

Host Your Alexa Skill Service on AMPLIFY using API Builder, Part 1

Host Your Alexa Skill Service on AMPLIFY using API Builder, Part 1

Host Your Alexa Skill Service on AMPLIFY using API Builder, Part 1

Host Your Alexa Skill Service on AMPLIFY using API Builder, Part 1