Amazon Alexa – Part 2, the backend

Stories about project management and coding

Amazon Alexa – Part 2, the backend

In this post I’ll discuss the requirements for an Alexa backend and how it handles Intents.

Amazon gives to the option to run your backend on it’s AWS Lambda environment (which has a small free tier) or you can host your own in your own infrastructure.
Your backend just has to accept JSON requests on port 443 via HTTPS from the outside, so you’re not bound to any programming language if you’re going for self-hosted environemnt, on Lambda you’re bound to Node.js, Python, Java or C#.
If you want to use your own infrastructure, be aware that you have to have a SSL certificate in place. The certificate can not be self-signed, it has to be signed by one of the trusted CAs.
But the good news here is that Amazon accepts Let’s encrypt certificates, so there’s a free option.

Besides the SSL configuration, using AWS Lambda as runtime environment makes the configuration easier, so in this series of posts we’ll concentrate on that.

The whole code mentioned in the snippets below can be found in the Github Repo for this post.
If you want to build the code, you’ll need JDK 8 and Maven 3.

The sample code

Amazon does provide some libraries that make your live easier when using Java, all you have to do is implement the Speechlet interface.
To be able to run it you have to include some AWS Lambda libraries, see the example pom.xml for these.

In repository you’ll find three important classes (among some helper classes, these are just there to make the code more readable)

  • ScheduleSpeechletRequestStreamHandler
    This class is created by the AWS Lambda environment when a request comes in. All calls will be dispatched to the Speechlet  passed into the super constructor.
  • ScheduleSpeechlet
    This is where the “magic” happens, in this class the Intents are processed
  • Launcher
    With this class you can launch a SSL configured Jetty server and enables you to run tests locally. The main method in this class configures the Jetty instance, adds the ScheduleSpeechlet  and starts it.

Example JSON

Request Signature

Alexa signs all HTTPS requests and to get your Skill certified by Amazon, you have to make sure your service checks the signature and the timestamps in the request.

While testing, you can disable this, but keep it in mind before submitting a skill.

Session

As you can see in the example JSON above, when the Alexa service communications with your backend, it always provides a session element.
This session object always has an attribut new , to indicate if this is the first call of the session, meaning the just just started the skill, with or without an Intent.

Speechlet

The methods in the Speechlet interface define:
– life-cycle events for the skill as experienced by the user
– a way to service speech requests from the user
– call-backs from events happening on the device the user is interacting with

The inteface defines four methods, two of them ( onSessionStarted , onSessionEnded ) are just event notifiers, you don’t have to return anything for these.

onLaunch

Entry point for Speechlets for handling a speech initiated request to start the skill without providing an Intent.
This method is only invoked when Session.isNew()  is true .

onIntent

As you can see, there isn’t anything complicated going on. We receive an Intent object, look up it’s name and fire our methods accordingly.
I also already included the built-in Intents, especially important here it the CancelIntent . Without it, you’ll have a hard time to cancel any action of your skill.

Local Testing

To run the code locally you can use the main  method in the Launcher  class.

I didn’t want to include the self-signed certifactes I used in the repository, to avoid anyone using them on their production environment.
Either disable the SSL configuration or quickly head over to my article on creating self-signed certificates for Javas Keystore.
Then make sure the following lines reflect your keystore location and password (notice that it isn’t a problem to put the keystore in src/main/resource if you run the main method in an IDE)

Next, make sure the following system property is set, otherwise all calls will be rejected, because the signature in the test JSON could not be verified.

Now you can use the main method to launch your service and use a simple rest client like Restlet to send the JSON found in /src/test/resources/test.json  to your service.

Local Test with Restlet successful

Buildung and deploying to AWS Lambda

To build the source go to the projects root directory and run

After this, you can find a jar file named  amazon-alexa-quickstart-1.0-jar-with-dependencies.jar in the target  directory.

Go to the AWS Console and login with your account (follow the instruction if you don’t already have one).
Under services, choose Lambda. Then make sure you have selected US East (N. Virginia) as AWS region in the upper right, as this is the only one providing a free tier for Lambda.

  • In the Lambda overview screen, select Create a Lambda function
  • We don’t need a blueprint, so select Blank Function
  • In the Configure triggers screen just select Next
  • In Configure function
    1. Name: should be unique, remeber this one
    2. Runtime: Select Java 8
    3. Lambda function code: Upload the previosly built amazon-alexa-quickstart-1.0-jar-with-dependencies.jar
    4. Lambda function handler and role
      • Handler: com.pmandcode.schedule.ScheduleSpeechletRequestStreamHandler (make sure to include the package name)
      • Role: Choose an existing role
      • Existing role: service-role/basicRole
      • Advanced settings, choose the lowest memory available (as our code doesn’t do much, it shouldn’t need much memory)
    5. Leave all others options and click Next, then Create Function

Configuration of your AWS Lambda function

After AWS Lambda is done configuring your function, in the upper right corner you can see your ARN ID – write this one done as we’ll need it later.

Example Test

You can now test your code running on Lambda. Click on Test, choose any Alexa event, paste in the test JSON mentioned earlier and press test, everything should come out OK.

With this we are done setting up the backend and can finish the Skill Configuration, as described in the next post.

Tags: , , , , ,

One Response

  1. […] part 2 of the series we’ll discuess how to get the Java backend source up and […]

Leave a Reply

Your email address will not be published. Required fields are marked *