The more I develop for Alexa, the more I learn about all of the features that are available to developers. One of the features that I have been wanting to implement for a while is a routine. Routines are a way to allow users to automatically launch a series of "actions" with a single "trigger."
Key Concepts
Before we get into implementation, let's first describe what a trigger and an action are. A trigger is the event that starts the routine. This could be many different things like a specific time, the sunrise or sunset, the beginning of a game of your favorite sports team, a specific prompt given to Alexa, and many more. An action is the thing that happens when the trigger is activated. This could be many different things like turning on a light, playing a specific song, reading the news, and many more. The Alexa team has already given us many pre-built actions that we can use, but we can also build our own custom actions associated with our custom skill.
The combination of these triggers and actions are what make up a routine. The user can set up a routine in the Alexa app, and then when the trigger is activated, the actions will happen in the order that the user specified on the specified device.
Implementation
Building a routine for your own custom skill is easier than you may think, so let's get into it.
1. Create a skill
You will need to have an Alexa Skill already built and deployed. If you don't have that yet, you can follow the official documentation to get started.
2. Define a custom task
Once you have your skill, go to your developer console and choose the skill you want to make a routine for. Under the "Custom" tab on the left, you will see "Tasks". Click on that and then click "Create Task". You will then give your task a name, the locales you want it to be available in, and the input that will be passed in when the task is triggered. An input isn't required, but if you need one to be passed in, you must choose the type, string or enum and then define the values that are allowed. Once those are filled out, click "Save Custom Task".
3. Validate and publish
Once you have your task created, you will need to validate and publish your skill. To validate click on the "Certification" tab. This will bring you to the validation page where you should see a button that says "Run". This will run the validation tests on your skill. If everything passes, you can then click on the "Submission" tab on the left and then click "Submit for review". Clicking this button will submit your new skill with the task created for review to the Alexa team. Your skill with the new task should be published once they approve it!
4. Create a handler for your task
Now that you have your task created and your skill published, you will need to create a handler for your task in your skill. This handler is just like any other intent handler, except you need to let Alexa know that it is a task handler. Here is an example of what that would look like in a Node.js skill:
const ReadWeeklyPromoTask = {
canHandle(handlerInput) {
return (
getRequestType(handlerInput.requestEnvelope) === 'LaunchRequest' &&
handlerInput.requestEnvelope.request.task?.name === '{YourSkillId}.{YourTaskName}'
);
},
async handle(handlerInput) {
return handlerInput.responseBuilder
.speak('Good morning!')
.withShouldEndSession(true)
.getResponse();
},
};
Once you have your handler created, don't forget to add it to your skill's request handlers! Also keep in mind the specificity of the canHandle method. Since this canHandle method is more specific than the a typical "LaunchRequest" handler, it should be placed before the "LaunchRequest" handler in your request handlers.
5. Test
Once you have your handler created, you can test it out in the Alexa app! You can create a routine in the Alexa app that triggers your task and then test it out on your device. If everything is set up correctly, your task should be triggered when the routine is activated! If the handler is functioning correctly, you are free to promote the new handler code to production.
Putting it all together
Once these steps have been followed you should be left with a few new and changed files. I will show you what mine looked like when I built my routine for my custom skill.
Task definition json
// ./skillDirectory/skillPackage/tasks/TaskName.1.json
{
"openapi": "3.0.0",
"info": {
"title": "Task name",
"version": "1",
"x-amzn-alexa-access-scope": "public",
"x-amzn-display-details": {
"en-US": {
"title": "Task name",
"description": "This is what the task does!"
}
// ...anyOtherLocales
}
},
"tags": [
{
"name": "task name"
}
],
"paths": {
"/TaskName": {
"summary": "Task Name",
"description": "Alexa will do this!",
"post": {
"requestBody": {
"content": {
"application/json": {
"examples": {
"sampleInput": {
"description": "Empty input",
"value": {}
}
}
}
}
},
"responses": {
"200": {
"description": "When the task does what it is suppose to do",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessfulResponse"
}
}
}
},
"400": {
"description": "When the given parameters fail validations"
},
"500": {
"description": "When the task fulfillment fails"
}
}
}
}
},
"components": {
"schemas": {
"SuccessfulResponse": {
"type": "object",
"properties": {
"endTime": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
The name of the file is important. It should be the name of the task with the version number at the end. The version number should be incremented each time the task is updated.
Skill json
// ./skillDirectory/skillPackage/skill.json
{
"manifest": {
"apis": {
"custom": {
// ...otherStuff
"tasks": [
{
"name": "ReadWeeklyPromo",
"version": "1"
}
]
}
// ...otherStuff
}
}
}
Your task should be listed in the skill.json file under the apis.custom.tasks array. The name should be the name of the task and the version should be the version of the task.
Handler
The code was shown above in the "Create a handler for your task" section, so I won't show it again here, but it should be included with your other handlers. Don't forget to add it to your request handlers export!
Conclusion
Routines are a great way to allow users to automate a series of actions with a single trigger and have been proven to increase user engagement and usability. I hope that this post has helped you understand how to implement a routine in your custom Alexa Skill!