We are currently at an intersection where the devices that we will work with will not necessary have an interface or buttons to click. One of the natural ways that we can interact with these devices is via voice. And one of the winners in the consumer device market in this segment is the Amazon Echo device. Since its release in mid-2015, it has found its way into homes where it performs a variety of tasks (called skills), prompted by users’ commands, and it responds back with the appropriate response.
The Amazon Echo device is not just a device that magically translates our voice into commands that it can understand and execute. Amazon has created an entire ecosystem that comprises the following:
- A range of hardware devices like Echo, Echo Dot, etc.
- The engine behind these devices, Alexa Voice Service is made available to manufacturers who would like to build out voice-enabled capabilities in their devices.
- A Software Development kit called Alexa Skills Kit that can be used by developers to build out custom skills.
- An Alexa Skills Marketplace that you can publish your skills to and on approval,is made available to anyone who owns an Amazon Echo device.
- An Alexa Skills Fund, that can help fund your ideas around the Alexa Voice Service.
- Last but not the least, one of its fastest growing services in AWS i.e. AWS Lambda is the easiest way that you can go about publishing your custom Alexa skill.
In this article, we are going to focus on the Alexa Skills Kit (ASK) and write our first custom skill. It assumes that you are familiar with the capabilities of the Amazon Echo device. Even if you do not own an Amazon Echo device, you can use the Amazon Echo simulator service to help test out your custom skill.
What Will we Build?
We are going to build an Alexa Skill for ProgrammableWeb. The skill will be kept simple and it will provide information on a Featured API and the top three popular API Categories. So we can interact with the Amazon Echo device by asking it sample queries as follows:
- Alexa, ask ProgrammableWeb to give me the featured API
- Alexa, ask ProgrammableWeb to list the top API categories
- Alexa, ask ProgrammableWeb what are the top categories
The above are just sample voice commands that we can ask to Amazon Echo. There can be multiple variations of it and we shall look at that in details as we build out the Alexa Skill.
Note: The Skill will use dummy data and we will not actually connect to any live API to retrieve the answer to our queries.
Alexa Skills Sample Projects
You can technically write the Alexa Skills in any programming language that you would like, as long as you are able to host the code on a server that the Alexa Service can communicate with. Amazon makes available sample projects in Node.js and Java, that you can look at to get started with writing your skills. The different sample projects offer a variety of conversational styles. For example the style that we will be using in our tutorial will be the one-off fire style, where we will ask a question and get a reply back. There are other conversational styles too where you can continue a conversation. Those are complex interactions worth looking into once you understand the basic process of publishing an Alexa Skill.
The sample projects for Node.js are available here. In particular, we have used the helloworld project and customized it in our post here for the skill that we wish to write. You can similarly use other samples to get a solid base on which you can build out your skills.
User Interaction Flow
The first step to writing an Alexa Skill is to understand how the device will interact with your custom skill and the flow from request to eventual voice response that the device will speak out once it receives the response from your service.
To understand that, take a look at the diagram shown below that has not just the user interaction flow but also gives you a workflow for the entire development, deployment and eventual invocation of your custom Alexa Skill.
Let us go through the steps that the diagram has highlighted. These steps are high level and we will see each of these steps as we go along in the tutorial.
Step 1 : Develop your code and deploy it on a hosting environment
This step requires that you should first design how the user will interact with your service and then write the code to interpret those commands. This requires that you chose an activation name for your service, select your sample utterances, and then write your code. It will also involve deploying your code to a hosting environment. We shall be using AWS Lambda for our tutorial.
Step 2 : Configure your Alexa Custom Skill
Once you have deployed your code, the next thing is to configure your skill. This requires that you have an Amazon Developer Account. You can configure your Alexa skill via the Amazon Developer Portal and can even test it out over there.
The next steps indicate how the user will interact with your service.
Step 3 : Interpret your Voice Command
When the user speaks out a command, for example “Alexa, ask ProgrammableWeb to give me the featured API”, the Alexa Voice Service converts that voice to text and interprets it. It will extract out the invocation command (ProgrammableWeb) and then work around some of its standard words to extract out the rest of the command i.e. “give me the featured API”. If the configuration is done correctly, it will map the intent to the available service that is hosted.
Step 4 : Invoke your Application Service that hosts the skill
The Alexa Service will then invoke your hosted service and receive the response.
Step 5 : Return the response to multiple devices
The response is then converted to both voice and an appropriate format for the companion mobile application.
Let us now move on to how we can implement the above steps.
Voice Interface Design, Intents and Sample Utterances
When you design the custom Alexa skill, you need to spend some time thinking about how the user is going to interact with your service via voice. This means a few things like:
Invocation Name
Identify the command that will be used to trigger your skill. For example the Amazon Echo is woken up by the word Alexa or Amazon or Echo. So the typical interaction will go like:
Alexa, ask <invocationname> to <Intent>In our case, we are going to go with the invocationname as ProgrammableWeb.
The Alexa Voice Service is designed in a way that allows you to be quite flexible in terms of the commands and the words/phrases around it.
For example we could interact with the same service in multiple ways as shown below:
- Alexa, ask <invocationname> to <Intent>
- Alexa, tell <invocationname> to <Intent>
- Alexa, ask <invocationName> <Intent>
- Alexa, ask <invocationName> for <Intent>
For more information on how you can design the Voice Interaction, check out the Voice Design Handbook.
Intents
The next thing to focus on is the Intent. If you are familiar with Android programming, then you will understand an Intent immediately. An Intent is the question that you are asking your Alexa Skill and which will result in the invocation of your service. Your Skill can support one or more Intents which are usually defined by a JSON file that is aptly titled IntentSchema.json.
As described earlier, we are going to write our skill that will give responses to two kinds of general requests: featured API and top API categories. So the IntentSchema.json file is where you define these two Intents. The file contents are shown below:
{
"intents": [
{
"intent": "FeaturedAPIIntent" },
{
"intent": "TopAPICategoriesIntent" }
]
}As you can see, your Alexa skill can have one or more intents. The intents are basically defined here by their name and what we see here is the simplest possible way to define an intent since we are only going to invoke the command and are not passing any variables or values while giving the command.
The Intent Schema is very flexible and can also take in parameters which are defined in slots. For more discussion on slots, refer to Intent Schema guide.
Utterances
So far we have finalized our Invocation Name (ProgrammableWeb) and our Intents. We now need to specify the various voice commands that would be spoken as part of the Intent. You can map to more than one utterance to make the voice command flexible.
Here is the Utterances file that we have for our two intents:
FeaturedAPIIntent featured API
FeaturedAPIIntent give me the featured API
FeaturedAPIIntent tell me the featured API
TopAPICategoriesIntent top categories
TopAPICategoriesIntent tell me the top categories
TopAPICategoriesIntent list the top categories
TopAPICategoriesIntent list top categories
TopAPICategoriesIntent give me the top categories
TopAPICategoriesIntent what are the top categoriesIt should be clear to you how we have mapped a single intent to multiple utterances. You can now speak any of the statements and the Alexa Voice Service will try and map it to the right Intent.
Continued from page 1.
In addition to Custom Intents, you can even handle multiple built-in Intents that Alexa Voice Service supports like the Help, Stop intents, etc. You can take a look at the Built-in Intents that are supported.
Writing our Custom Skill Code and Deploying it via AWS Lambda
As mentioned earlier, we are going to use the helloworld sample and customize it to fit our custom Alexa Skill. We will specifically just look at the index.js file where we need to handle the code for our specific Intents. The index.js file is shown below:
/**
* App ID for the skill
*/
var APP_ID = undefined; //replace with "amzn1.echo-sdk-ams.app.[your-unique-value-here]";
/**
* The AlexaSkill prototype and helper functions
*/
var AlexaSkill = require('./AlexaSkill');
/**
* ProgrammableWeb is a child of AlexaSkill.
* To read more about inheritance in JavaScript, see the link below.
*
* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Introduction_to_Object-Oriented_JavaScript#Inheritance
*/
var ProgrammableWeb = function () {
AlexaSkill.call(this, APP_ID);
};
// Extend AlexaSkill
ProgrammableWeb.prototype = Object.create(AlexaSkill.prototype);
ProgrammableWeb.prototype.constructor = ProgrammableWeb;
ProgrammableWeb.prototype.eventHandlers.onSessionStarted = function (sessionStartedRequest, session) {
console.log("ProgrammableWeb onSessionStarted requestId: " + sessionStartedRequest.requestId
+ ", sessionId: " + session.sessionId);
// any initialization logic goes here
};
ProgrammableWeb.prototype.eventHandlers.onLaunch = function (launchRequest, session, response) {
console.log("ProgrammableWeb onLaunch requestId: " + launchRequest.requestId + ", sessionId: " + session.sessionId);
var speechOutput = "Welcome to Programmable Web via Alexa Skills Kit";
var repromptText = "You can say top categories or featured APIs";
response.ask(speechOutput, repromptText);
};
ProgrammableWeb.prototype.eventHandlers.onSessionEnded = function (sessionEndedRequest, session) {
console.log("ProgrammableWeb onSessionEnded requestId: " + sessionEndedRequest.requestId
+ ", sessionId: " + session.sessionId);
// any cleanup logic goes here
};
ProgrammableWeb.prototype.intentHandlers = {
// register custom intent handlers
"FeaturedAPIIntent": function (intent, session, response) {
output = "Today's featured API is the YouTube API. The Data API allows users to integrate their program with YouTube and allow it to perform many of the operations available on the website. It provides the capability to search for videos, retrieve standard feeds, and see related content. " response.tellWithCard(output, "ProgrammableWeb", output);
},
"TopAPICategoriesIntent": function (intent, session, response) {
output = "Top API categories for today are Shopping, Search and SMS";
response.tellWithCard(output, "ProgrammableWeb", output);
},
"AMAZON.HelpIntent": function (intent, session, response) {
response.ask("Hi I am the Programmable Web API Skill. I can tell you about the featured API and top API categories", "Hi I am the Programmable Web API Skill. I can tell you about the featured API and top API categories");
}
};
// Create the handler that responds to the Alexa Request.
exports.handler = function (event, context) {
// Create an instance of the ProgrammableWeb skill.
var pw = new ProgrammableWeb();
pw.execute(event, context);
};What is important to focus on in the code above are the intentHandlers. You will find that we have provided the implementation for 3 intents:
- FeaturedAPIIntent : This returns the API that we want to mention as the featured API.
- TopAPICategoriesIntent : This returns the list of categories that currently are the most popular.
- AMAZON.HelpIntent: This is a built-in intent and we are overriding it to give some information on our Alexa skill.
Deploy the Skill
We shall be using AWS Lambda to deploy our code. This assumes that you have an Amazon Web Services account. The first step is to create a ZIP file with all of your sources. In our case, we have taken the index.js and AlexaSkill.js files in the src folder and created a skills.zip file.
The next step is to deploy our code via AWS Lambda service. The steps to do that are given below:
1. Sign in to your AWS account via the console and ensure that you are in the US East region.
2. Select the AWS Lambda service from the list of services.
3. We are going to create a new Lambda function. Click on the Create a Lambda function button. This will bring up the “Select blueprint” window. Scroll down and click on Next.
4. This will bring up the option of configuring a trigger. A trigger is what will invoke our Lambda function. This is obviously the Alexa Skills Kit. So just click on the empty trigger option as shown below.
Then select Alexa Skills Kit from the drop down list. Click on Next.
5. The next step is to provide details about your function. It consists of multiple sections as given below:
Give a name to your Lambda function and a description. Select the runtime as Node.js as given in the screenshot above. The next thing is to upload our code. Select Upload a .ZIP file and click on Upload to upload the skills.zip file that we just created.
In the Lambda function handler, keep the name as index.handler since that will look into the file index.js. For Role, click on Create a custom role. This will bring up a new window. Just select the IAM Role as lambda_basic_execution and click on Allow.
Leave the Advanced settings as is and click on Next.
6. On the Review page, click on Create function. This will create the function and you should see a success message as shown below:
7. Note down the ARN that you see in the top right of the window above. We will need this to associate our Alexa Skill with the AWS Function that we just created in the next step.
Configuring our Custom Alexa Skill via Alexa Developer Portal
Now that we have our code deployed along with the Intent Schema and sample Utterances file, it is time to configure our custom Alexa skill. Follow the steps given below:
1. Go to Amazon Developer Portal and sign in with your developer account.
2. Click on the Alexa tab and then click on the Alexa Skills Kit. This will lead you to a list of your current configured skills. Click on Add a New Skill button.
3. This will bring up the Skill Information section, which we have filled out as given below:
Note that the Name can be anything but remember to use the correct Invocation Name here i.e. programmableweb. Click on Next.
4. The next section is that of the Interaction model. You will need to keep your Intent Schema and the Sample utterances ready. Paste them into the respective sections as shown below:
And click on Next. This will build out your Interaction Model and do some validations to ensure that the correct phrases and words have been used in terms of naming conventions and allowed words, etc.
5. Finally, we have to associate this skill with its AWS Lambda function. We had saved the ARN from our deployed AWS function, paste that as shown below and select No for account linking. Click on Next.
If everything goes well, your Custom skill has been configured, enabled and can be tested now. Stay at the same screen in the Alexa Skills configuration.
Testing out our Custom Skill
To test out your skill, you will find the Service Simulator in the Test section. You can provide any of the utterances and test out the request and response data that is sent and retrieved by the Alexa Voice Service.
For example, we try out one of the utterances i.e. featured API and it will provide the output as shown below:
What it has done behind the scenes is that it mapped the utterance to the Intent i.e. FeaturedAPIIntent, then it invoked the code that handled the Intent and displayed the results. When it is finally delivered to the Amazon Echo device, the Voice service will translate the content text into voice and say it.
Amazon has also made available a nice Web application echoism.io, where you can login with your account and start testing out the skills.
Moving forward
We have tested out the skill in the Service Simulator. You can also test it out on the device. If you are signed into Alexa with the same account, you can simply begin by saying “Alexa, ask ProgrammableWeb featured API” and it will say out the featured API that the function returns.
You can also publish this skill though that would require that you complete the rest of the steps in the Alexa Skill Configuration and submit it for approval to the Alexa Marketplace team. You will need to follow the guidelines as laid out in the Alexa Skills Marketplace. Take a look at the certification process for a custom skill.
Conclusion
The Amazon Echo is an excellent device and Amazon has just announced that there are 1400+ skills now available for everyone. The barrier to writing a custom skill is not very high and with sample code available, it is a straightforward process. What is equally if not more important is to spend time designing your skill, what value it will bring to the users and how they can interact with it. Keep in mind that the experience is hands-free and voice driven and not every Web application might be well tuned to this way of interaction. The skills marketplace is still nascent and it presents a great opportunity for anyone to come up with skills that could become popular.