Build an Alexa Skill in Java (Part 1 of 2)

In trying to learn how to create an Alexa Skill using Java, I realized that there is absolutely no real tutorial for it. There are tutorials for NodeJS and Python. Lots of them! But as for Java — well, you have sample code. If you’re a Java developer wanting to create an Alexa Skill, then follow along!

Before I give you the actual how-to on developing an Alexa Skill, let’s try getting a pre-made Hello World skill working. First you need …

The Alexa Skills Kit SDK

Requirements:

  • The Alexa Skills Kit SDK source code
  • Java 8 JDK (You can use Java 8 OpenJDK as well)

Head on over to the SDK’s repo https://github.com/amzn/alexa-skills-kit-java. Download the zip file and unzip it in your target folder. Or you can just fork it and clone your copy. Personally, I’d rather fork it.

The project contains two Maven build files. The one at the root of the project is used to build the SDK library. The other is in the samples folder which would allow you to build the different Alexa Skill samples. Normally I would tell you to just follow the README file found in the sample Skills. But I’ll save you the trouble: DON’T. Well, at least not in its entirety.

Let me just say this first: I have never used Maven. If you’ve used Maven before, then you’ll figure out quickly that something is very wrong with the folder structure of the project and will be able to fix this lickity split. But if you’re as green to Maven as I am, you’ll notice that following the README results in a non-working build.

We just want to get Hello World done and working as fast as possible. So, go into src. Copy the com folder. Paste it into samples/src/main/java/. Now go into samples. Run this command to build the JAR file.

mvn assembly:assembly -DdescriptorId=jar-with-dependencies package

It should generate a target folder inside samples containing two JARs. We’re using alexa-skills-kit-samples-1.0-jar-with-dependencies.jar. Got it? Ok, we’re all set to set up our first Alexa Skill!

Set up an AWS Lambda function for your Alexa Skill

First we need a place to run our Skill on. For that, we’ll be using AWS Lambda. If you don’t have an AWS account, then start by creating one. Don’t worry. Creating an account is free. Plus, you get to use the services for free during your first year. Unlike the other AWS services, use of AWS Lambda continues to be free beyond your first 12 months. Kinda. See details here: https://aws.amazon.com/free.

Again, if you try to follow the README and you’ve never used AWS Lambda, you’ll pretty much get lost somewhere in the middle because the directions don’t match what you’re actually seeing. You’re better off following the directions in https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/alexa-skill-tutorial. But that tutorial teaches you to install one of AWS’s pre-made skill blueprints, not upload one you made yourself. We’ll still follow it, but do notice the slight difference in steps.

Enough chatter. Let’s set it up!

  1. Log in to the AWS Management Console.
  2. Select Lambda from the list of services
  3. Click the region drop-down in the upper-right corner of the console and select either US East (N. Virginia) or EU (Ireland). As of this writing, those are the only supported regions for Lambda functions used with the Alexa Skills Kit.
  4. Choose “Get Started Now”. SKIP “SELECT BLUEPRINT”. Click on “Configure triggers” instead.
  5. See that outlined empty square? Click on that. Select “Alexa Skills Kit”. Now click “Next”.
  6. Give your Lambda function a name. My-Hello-World-Skill is ok. Don’t use spaces.
  7. Choose Java 8 as your runtime.
  8. Now, upload the alexa-skills-kit-samples-1.0-jar-with-dependencies.jar we generated earlier.
  9. Scroll down to the “Lambda function handler and role”. Type helloworld.HelloWorldSpeechletRequestStreamHandler in Handler.
  10. For the Role, select “Create a custom role”. When the IAM role management console opens, choose “Allow.” and you’ll be taken back to the previous Lambda console. The role will now be populated with lambda_basic_execution. Choose “Next”.
  11. Choose “Create function”. Copy the Amazon Resource Name (ARN) displayed in the upper-right of the console. For example: arn:aws:lambda:us-east-1:xxxxxxxxxxxx:function:My-Hello-World-Skill

That’s it. We’ve uploaded our code into AWS Lambda. Now we need to tell Alexa that our Hello World Skill exists.

Configure the Skill

Again, the directions in https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/alexa-skill-tutorial are pretty much what we’ll be using for the most part.

  1. Sign in to the Amazon developer portal at https://developer.amazon.com. If you haven’t done so already, you’ll need to create a free account.
  2. Select “Alexa” from the top navigation bar.
  3. Under “Alexa Skills Kit,” choose “Get Started >”.
  4. Choose “Add a New Skill”.
  5. Set “HelloWorld” as the skill name and “greeter” as the invocation name, this is what is used to activate your skill. For example, you would say: Alexa, tell Greeter to say hello. Click “Next”.
  6. In the /samples/src/main/java/helloworld/speechAssets folder, you should see the file IntentSchema.json. Open that up and copy the contents of that into the “Intent Schema” text box. I’ll explain this in Part 2 of my tutorial.
  7. In the same folder, you’ll have the file SampleUtterances.txt. Open that up too. Copy the contents of that into the “Sample Utterances” text box. Again, I’ll explain this in Part 2 of my tutorial.
  8. Choose “Next” and wait until the Interaction Model is finished loading (in no more than a few seconds).
  9. I hope you copied your ARN earlier. Because you’re going to need it now. Select “AWS Lambda ARN” for the service endpoint type. Pick the geographical location that matches where your Lambda is located and paste your ARN. Select “No” for “Account Linking.” Then hit “Next.”

You’re done! Well, almost.

Upload your JAR file. Again.

Wait, what? I already did that!

Well, there’s a chicken-and-egg problem here. Let me explain.

  • Your Skill service needs an Application ID (appID) in order to be recognized by Alexa.
  • Your appID can only be created after you configure the skill.
  • You need the ARN generated after creating your AWS Lambda function in order to configure the Skill.
  • You need to upload your Skill to create your AWS Lambda function.
  • Did I mention you need the appID in your Skill in order to be recognized by Alexa?

Right. We’re still inside the Amazon Developer Console.

  1. Go back to the skill Information tab and copy the appId. It would look something like amzn1.ask.skill.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
  2. Open samples/src/main/java/helloworld/HelloWorldSpeechletRequestStreamHandler.java. You’re looking for amzn1.echo-sdk-ams.app.[unique-value-here]. Replace that whole thing with your appID. REMEMBER: the whole thing. Not just the part that says [unique-value-here. Save the file.
  3. Build your JAR again.
  4. Go back to the AWS Lambda console and upload the now authorized JAR.

You should be good to go by now! Say “Alexa, tell Greeter to say hello.” It should reply with “Hello World”. Uhm, yes. I’m assuming you have an Amazon Echo or Echo Dot. You don’t? Well, no worries. It’s much better if you have the Echo/Echo Dot for real world testing. But another option is to go to the “Test” section of your Skill inside the Amazon Developer Console. You should see a “Service Simulator” there. Enter an utterance. Like tell greeter to say hello. Then click “Ask HelloWorld”. It should give you Lambda JSON request and response.

Not working? The problems I encountered were due to the following.

  • Wrong appID value
  • Wrong intent schema
  • Wrong sample utterances
  • Wrong ARN
  • Wrong or no specified role in AWS Lambda
  • Corrupted build

Double check that stuff first. Still not working? Go back to the AWS Lambda function you created. Hit the “Test” button. If it throws Could not validate SpeechletRequest null using verifier ApplicationIdSpeechletRequestEnvelopeVerifier, rejecting request, that’s normal because you’re running the handler without passing an utterance. Other than that, then something is wrong with your build. Leave a comment below if you’re stuck.

It’s working! Now what?

Congratulations! Now that we know how to install and configure a Java-based Alexa Skill, it’s time we learn how to build our own! Up next: PART 2!

Share Comments
comments powered by Disqus