Alexa skill tutorial: How to write your first voice-assistant app

Under Global Fields where it says Endpoint and Service Endpoint Type, click the radio button next to AWS Lambda ARN (Amazon Resource Name), the recommended option. Paste the ARN string into the Default group. You can also provide a geographic option—North America for the N. Virginia datacenter you selected earlier—and then paste that ARN code into the text box that appears as well. Leave everything else at the default (this skill doesn’t need account linking or any other extra permissions), then click Save and Next.

Step 7: Test the default Alexa skill

You should now be at your skill’s test page. There are a few ways you can test:

• If you have an Alexa device nearby that’s connected to the same Amazon account you used to develop the skill, the directory skill should already be available on your device. Say “Open “ and the name of your skill, and it will tell you what to do.
• If you want to voice test but don’t have Alexa hardware handy, you can try a web-based third-party testing tool at Echosim.io. You’ll need to connect your Alexa account to the service. There’s also a separate, third-party app called Reverb available for MacOS, iOS, and Android. However, if there’s a problem with your skill, you won’t know if the problem is the third-party platforms being flaky or something wrong with your code.
• You can do text-based testing on this Amazon developer console test page, which is your best way to track down errors. Scroll down to the Service Simulator and type in something the user would say after your skill is opened. help is often a good starting point, just to see if it’s working at all. The help text will give you a suggested command to try, which you can type into the Enter Utterance box (replacing help).

IDG

With the Service Simulator, you’ll see the code that’s sent to your Lamba function and the code that’s returned. If you click the Listen button below the returned code, you’ll hear how the response sounds if Alexa speaks it. Next, try typing in the suggested query who is paul cutsinger. And so on.

If your skill isn’t working, you’ll usually see a generic warning “The remote endpoint could not be called, or the response it returned was invalid.” For more helpful information about what went wrong, first copy all the code in the Lambda Request box. Then head back to your skill’s Lambda function in your AWS console.

Under Actions, choose Configure test event. For the sample event template, pick Alexa Start Session (there are a lot of possible sample events; you may need to use the search box). Delete the default code and paste in the code you copied from the Lambda Request box between the existing braces ({}) in that box. Click Save and Test. If there’s still an error, you should see a Details dropdown, hopefully with more information that will help you debug. There should also be a link to a cloud log, which may have more information still.

Step 8: Customize the Alexa skill

It’s pretty straightforward to keep everything the same in this skill except for using your own data and tweaking some phrases that Alexa says to the user.

Many Node.js skill templates (including this one) hard-code data in the index.js file. Using your own data means swapping in your data in JSON format. Make sure to use the same exact category names as the original data, including whether they’re uppercase or lowercase. If the sample data values are all lowercase, make sure yours are as well—that can matter (and in fact does matter for this skill).

For data that changes often, hard-coding in the index.js file isn’t very practical. Amazon has some examples of how to read in data from a static file on its S3 storage service or NoSQL database DynamoDB.

You’ll find text for Alexa’s response messages in the index.js file. Doing a text search for “message” may help you locate most of them. This particular skill has Alexa talking about finding “evangelists,” something that you’ll probably want to change. Search for those words in the index.js file.

If you want to change the structure of a skill template, such as creating a directory with phone and email information but not LinkedIn or GitHub, I advise first cataloging all the features of the skill as it exists. Go to the Developer Console and write down all the slots (variables) and intents you see, and next to each whether you will keep it as is, change it, or delete it. For the intents you’re keeping, check whether the sample utterances work for your use case or if you need to add or delete some.

If you are adding a slot, you need to assign it a slot type, either built-in or custom. If you’re adding an intent, it needs sample utterances and may need slots.

If you add or change slots and intents, the index.js back-end code needs to change as well. The second section of this skill’s index.js file warns: “CAUTION: Editing anything below this line might break your skill.” However, if you’ve changed category names, not editing code below that line will break your skill.

Each customization is different, but here’s some general advice: It’s a good idea to search for the name of every slot and intent within index.js, whether you’ve deleted it, changed it, or kept it as is. You can find some interesting things in the code that way. For example, if you are keeping github and didn’t search for it, you wouldn’t have seen this:

if (slots.infoType.value =="git hub"){
           infoTypeValue ="github";
           console.log(“resetting gith hub to github”);
      }

which changes spoken “git hub” to “github” (because Alexa might see “github” and assume it was pronounced “gith-ub” instead of “git-hub”). That’s useful code if you’re adding a slot that also has pronunciation problems.

Searching for each slot name also uncovered this code at the end of the index.js file:

function isInfoTypeValid(infoType){
      var validTypes = [“git hub”,”github”,”twitter”,”linkedin”];
      return isInArray(infoType,validTypes);
 }

You don’t have to be a JavaScript expert to see that the function is checking to ensure the infoType is git hub, github, twitter, or linkedin. If you added or changed an infoType without also updating this function, your new category will be deemed invalid and thus won’t work..

If you’re adding an intent and aren’t a Node.js expert, the best advice I can offer is to find a template with an intent that accomplishes a similar goal, then adapt it.

Step 9: Publish your Alexa skill

If you want to make your skill public, the Publishing Information page that comes after the Test page in the developer console has most of the information you need.

Published skills need info such as a short and long skill description, sample utterances, and small and large images. Note that when Amazon says it wants the small icon to be 108 by 108 pixels, that’s an exact requirement, not an estimate—I was rejected for being off by just a couple of pixels. You’ll also have to fill out the Privacy & Compliance page after the publishing info page. Submit and then wait to hear if you’re approved.

If you want to create private skills for within your organization, Amazon offers Alexa for Business, with enterprise features such as managing users annd device locations. Monthly pricing starts at $7 per enrolled user and $3 for shared device.

If you just want your skill to be private among some family and friends, you can go through the publishing process until actually submitting it for review -- including adding an image -- and then create a private beta test and invite users.

A different process for Alexa skills: command line

Finally, you may soon find it cumbersome to manually upload or copy and paste files to both the developer console and Lambda, not to mention having to switch between browser tabs for various tasks. That’s why Amazon recently released its Alexa Skills Kit Command-Line Interface (ASK-CLI) tool. Note: You’ll need Node.js to install it locally.

Resources for creating Alexa skills

This tutorial should have helped you get your own corporate directory or personal phone book up and running on Alexa. If you’d like to continue your skill-building journey, here are some more resources that can help:

Alexa skill voice design

• Amazon design tools: Advice and worksheets from Amazon on designing a voice interface.
• Voice design basics: A two-minute video from Amazon Alexa developers giving an overview of voice concepts.

Additional Alexa skill tutorials

• Developing Alexa Skills: Amazon teamed with tech instructors Big Nerd Ranch for a six-part video tutorial on building Alexa skills. (Note: If you’ve got an Alexa device in the room, turn off its microphone or put on headphones if you don’t want it to keep getting triggered from the video.)
• Python tutorial: Amazon’s quick start for Python.
• Amazon also has on-demand webinars and third-party training videos in its developer console (some of the external videos require payment to watch a full course).

Alexa skill templates

• Local recommendation guide:  Amazon uses this in some of its beginner “developer day” sessions. It features how to return random results from a group of acceptable responses.
• External calls: This is Amazon’s template for how to call a web API in an Alexa skill. Also see this non-Amazon example of pulling weather information from Weather Underground by engineering physicist Kevin Loeffler.
• Google calendar reader: Be warned that the Node.js iCal parser used in this skill (separate from Alexa-specific code) doesn’t handle repeating events.
• Trivia: This is a question-and-answer trivia skill, by Amazon.
• Quiz game: This keeps score in addition to asking trivia (or other) questions. It also uses speechcons, which give Alexa more expressive speech for some words.
• Help following a (cooking) recipe: The actual skill may not be that compelling, but this skill demonstrates how to save and access user state—people can stop using a skill and then pick up where they left off.
• Pet match: This skill prompts the user for multiple pieces of information and then tries to find the best match by using an API.