Integrate Your Custom Task with Alexa Routines
customtasksinroutines. Child-directed skills and HIPAA skills aren't eligible to use connections between skills, and therefore can't integrate custom tasks with Alexa routines.
You can integrate custom tasks with Alexa routines to increase user engagement with your skill.
As a starting point, you can either create a new custom task or you can use an existing custom task that you created for skill connections or quick links. Then, follow the instructions on this page to make your task compatible with routines.
You can create or update your custom task for routines by using the Alexa developer console or the command line.
This topic uses a fictional "My News" skill as an example.
What are Alexa routines?
An Alexa routine consists of a trigger and a sequence of actions. The trigger is an event such as a time of day (for example, 7:00 AM) or a user request such as, "Alexa, start my Morning Session." The sequence of actions is a list of tasks for Alexa to perform when the trigger happens. For example, Alexa can deliver a news briefing and then tell the weather forecast. Users can enable built-in Alexa routines or create their own custom routines by choosing triggers and routine actions from the Routines section in the Alexa app.
The following sections describe how to expose a custom task in your skill as a routine action so that users can add the action to their custom routines.
How do custom tasks appear in the Alexa app?
When you define and publish a custom task and integrate it with Alexa routines, the task appears as an action that users can choose when they create a custom routine in the Alexa app.
For example, a user of a "My News" skill would take the following steps to add a routine that calls a custom task of the "My News" skill:
- The user enables the "My News" skill, either by using the Alexa app or by voice.
- In the Alexa app, the user goes to More > Routines.
- The user taps +.
- The user enters a routine name.
- The user taps When this happens, and then selects a trigger.
- The user taps Add action > Skills > Your Skills > My News.
"My News" displays a default launch task ("Open My News") and three custom tasks, as shown in the following screenshot.
- The user selects the default task or one of the custom tasks.
The following screenshot shows the confirmation screen when a user selects the default task.Note: For this default task, the Alexa app uses a template to display the string "Alexa will open {skill Name}." In this description, "My News" is the name of the skill, which is extracted from the skill manifest.
- The user saves the routine.
Custom task requirements and limitations
To integrate with Alexa routines, your task must meet the following requirements:
- Your task must be certified, published, and available in each marketplace that you designated. For details, see Develop Skills in Multiple Languages and Define Skill Store Details for Publication.
-
In the task definition file, you must set the
x-amzn-alexa-access-scopefield topublic, notvendor-private.Note: Your skill will fail certification if the custom task's displayed information includes profanity.
The following limitations currently apply:
- To integrate with Alexa routines, custom tasks can have no more than one input parameter.
- Task versioning isn't supported.
Steps to integrate a custom task with Alexa routines
To integrate a custom task with Alexa routines, take the following steps:
- Create a custom task.
- Choose locales.
- Update the task definition file.
- Validate your skill.
- Certify and publish your skill.
Step 1: Create a custom task
If you haven't already done so, follow the instructions in Implement Custom Tasks in Your Skill to build a custom task in your skill.
To find the custom task section of the developer console
- Log in to the developer console, and then navigate to your skill.
- On the left, under CUSTOM, choose Tasks.
Alternatively, you can create or update your custom task for routines by using the command line.
Step 2: Choose locales
Determine the locales where you want to make your custom task available in Alexa routines. Available locales are en-AU, en-CA, en-IN, en-GB, en-US, fr-CA, fr-FR, de-DE, hi-IN, it-IT, ja-JP, pt-BR, es-ES, es-MX, and es-US.
For each chosen locale, you must provide a user-friendly task title and task description in the task definition file, as the next step describes.
Step 3: Update the task definition file
You must provide user-friendly strings for your task title, task description, input parameter name, and description in the appropriate language in the task definition file. The Alexa app displays these strings to users.
If your custom task uses input parameters, you must provide titles and descriptions for the input parameters also.
For details, see Task definition files for custom task types.
Step 4: Validate your skill
You can validate your skill by using the Alexa Skills Kit developer console in the following way.
To validate your skill
- Log in to the developer console, and then navigate to your skill.
- At the top, click the Certification tab.
- Click Run.
- After the validation is complete, look for any warnings or error messages.
You must address the warnings and error messages if you want users to see your custom task when they set up a routine.
For details about validating skills, see Validate and test your skill.
development stage. For details, see Test Your Custom Task with Alexa Routines.Step 5: Certify and publish your skill
Before users can see your custom task when they set up a routine, you must certify and publish your skill. For details, see Submit the skill and Publish a skill that has been certified.
Before you submit your skill for certification, keep the following points in mind:
- As part of skill certification, Amazon validates the task schema to ensure compatibility with routines.
- The schemas of the custom tasks mentioned on this page are the only schemas that support integration with routines.
- If the task title and description for a given locale are missing from the task definition file, the task doesn't appear in Alexa routines for that locale.
- If your custom task isn't compatible with routines, you can still use your custom tasks with skill connections and quick links as long as the validation step doesn't return an error message.
After your skill is certified and published to the live stage, your skill's custom tasks are available as actions in Alexa routines.
Task definition files for custom task types
Alexa routines currently supports three types of custom tasks:
- Custom tasks with no input parameters
- Custom tasks with a single-string input parameter
- Custom tasks with a predefined set of inputs that your skill supports
The following sections describe the fields that you must include in the task definition file to integrate the supported custom task types with routines.
Custom tasks with no input parameters
The following table shows the task definition file fields that you must include when you integrate a task with no input parameters with Alexa routines.
| Field | Description | Type | Required? |
|---|---|---|---|
|
|
Name for your custom task. The Alexa app displays this name to users in the specified locale. |
String |
Yes |
|
|
Description of what your custom task can do. The Alexa app displays this description to users in the specified locale. |
String |
Yes |
|
|
You must set this field to |
String |
Yes |
responses object. For details, see Responses object in the task definition file.Example
The following example shows a task definition for a "News update" custom task. This task doesn't require an input parameter from the user. To enable the task for routines, the x-amzn-display-details field contains user-friendly strings for the task title and description.
{
"openapi":"3.0.0",
"info":{
"title":"News update",
"version":"1",
"x-amzn-alexa-access-scope":"public",
"x-amzn-display-details":{
"en-US":{
"title":"News update",
"description":"Play news update"
},
"es-US":{
"title":"Actualización de las noticias",
"description":"Reproducir actualización de noticias"
}
}
},
"paths":{
"/NewsUpdate":{
"post":{
"requestBody":{
"content":{
"application/json":{
"examples":{
"sampleInput":{
"description":"Empty input",
"value":{
}
}
}
}
}
},
"responses":{
"200":{
"description":"When the test finishes successfully",
"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 Alexa app displays the user-friendly strings that you provide in the info object in the Routines action list. In this case, there are no input parameters. When the user chooses "News update" from the action list, the Alexa app takes the user to a confirmation screen.
The following screenshot shows a confirmation screen for a "News update" task that has no input parameters.
Custom tasks with a single-string input parameter
You can create a custom task that has a single-string input parameter. For these tasks, consider the following recommendations:
- Minimum and maximum length of the input – You can use the optional fields
minLengthandmaxLengthto specify the minimum and maximum lengths of the string that the user can enter as the input parameter value. The value ofminLengthmust be a positive integer. The value ofmaxLengthmust be greater than or equal tominLength. The default value ofmaxLengthis 100 characters. - Unexpected text input – Because the Alexa app allows users to enter arbitrary strings for your input parameter, your task must gracefully handle any unexpected text input. For example, if the user enters text input that your task doesn't support, provide a response that informs the user that the value entered isn't supported.
The following table shows the task definition file fields that you must include when you integrate a task with a single-string parameter with Alexa routines.
| Field | Description | Type | Required? |
|---|---|---|---|
|
|
Name for your custom task. The Alexa app displays this name to users in the specified locale. |
String |
Yes |
|
|
Description of what your custom task can do. The Alexa app displays this description to users in the specified locale. |
String |
Yes |
|
|
Title for the input parameter. |
String |
Yes |
|
|
Description of what the input parameter can do. |
String |
Yes |
|
|
You must set this field to |
String |
Yes |
responses object. For details, see Responses object in the task definition file.Example
The following example shows a "Stock update" custom task. Like the "News update" custom task in the previous example, this task has the x-amzn-display-details field that contains user-friendly strings.
This task requires a single-string input parameter, the stock symbol. A separate x-amzn-display-details field in the paths object contains the user-friendly strings for the parameter name and description.
{
"openapi":"3.0.0",
"info":{
"title":"Stock update",
"version":"1",
"x-amzn-alexa-access-scope":"public",
"x-amzn-display-details":{
"en-US":{
"title":"Stock update",
"description":"Alexa will provide you the stock update for the chosen stock."
},
"es-US":{
"title":"Actualización de stock",
"description":"Alexa le proporcionará la actualización de stock para el stock elegido."
}
}
},
"paths":{
"/StockUpdate":{
"post":{
"requestBody":{
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/Input"
},
"examples":{
"testExample":{
"summary":"Example input for Stock update task",
"description":"Example input for Stock update task",
"value":{
"company":"AMZN"
}
}
}
}
}
},
"responses":{
"200":{
"description":"When the test finishes successfully",
"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":{
"Input":{
"type":"object",
"properties":{
"company":{
"type":"string",
"x-amzn-display-details":{
"en-US":{
"name":"Stock symbol",
"description":"Enter stock symbol"
},
"es-US":{
"name":"Símbolo stock",
"description":"Ingrese el símbolo de stock"
}
}
}
}
},
"SuccessfulResponse":{
"type":"object",
"properties":{
"endTime":{
"type":"string",
"format":"date-time"
}
}
}
}
}
}
In this case, the action contains a string input parameter. When the user chooses "Stock update" from the action list, the Alexa app takes the user to a screen with a text input field. The Alexa app displays the user-friendly string that you provide in the info.x-amzn-display-details.{locale}.description of the paths object as the hint text for the input field.
The following screenshot shows an input screen for a "Stock update" task that has a single parameter. Alexa displays the "Enter stock symbol" prompt where the user can enter the chosen stock symbol as string input.
When the user taps the prompt and then enters the stock symbol, the prompt disappears and the Alexa app displays the stock symbol.
Custom tasks with a predefined set of inputs that your skill supports
You can create a custom task that has a predefined set of inputs. For a given custom task, you can have a maximum of 100 predefined inputs.
The following table shows the task definition file fields that you must include when you integrate a task with a predefined set of inputs with routines.
| Field | Description | Type | Required? |
|---|---|---|---|
|
|
Name for your custom task. The Alexa app displays this name to users in the specified locale. |
String |
Yes |
|
|
Description of what your custom task can do. The Alexa app displays this description to users in the specified locale. |
String |
Yes |
|
|
Title for the input parameter. |
String |
Yes |
|
|
List of resolvers for the |
Object |
Yes |
|
|
Inputs that you define. Maximum length for a predefined input parameter: 50. |
String |
Yes |
|
|
You must set this field to |
String |
Yes |
responses object. For details, see Responses object in the task definition file.Example
The following example displays a list of news categories for users to choose from. Users can select one of the displayed news categories. The task delivers a news update from the selected category.
{
"openapi": "3.0.0",
"info": {
"title": "News category",
"version": "1",
"x-amzn-alexa-access-scope": "public",
"x-amzn-display-details": {
"en-US": {
"title": "News category ",
"description": "Alexa play news update from the selected news category."
},
"es-US": {
"title": "Categorí de noticias",
"description": "Reproducir actualización de noticias de la categoría de noticias seleccionada."
}
}
},
"tags": [{"name": "News category"}],
"paths": {
"/NewsCategory": {
"summary": "News category",
"description": " Alexa play news update from the selected news category.",
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Input"
},
"examples": {
"testExample": {
"summary": "Example input for Play News Update Task",
"description": "Example input for Play News Update Task ",
"value": {
"News Category": "POLITICS"
}
}
}
}
}
},
"responses": {
"200": {
"description": "When the task finishes successfully",
"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": {
"Input": {
"type": "object",
"properties": {
"enumName": {
"type": "string",
"enum": [
"POLITICS","SPORTS","BUSINESS","TECHNOLOGY"
],
"x-amzn-display-details": {
"en-US": {
"name": "News category",
"enums": {
"POLITICS":"Politics",
"SPORTS":"Sports",
"BUSINESS":"Business",
"TECHNOLOGY":"Technology"
}
},
"es-US": {
"name": "Categoría de noticias",
"enums": {
"POLITICS":"Política",
"SPORTS":"Deportes",
"BUSINESS":"Negocio",
"TECHNOLOGY":"Tecnología"
}
}
}
}
}
},
"SuccessfulResponse": {
"type": "object",
"properties": {
"endTime": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
The following screenshot shows a custom task called "News category" that offers four different news categories. The user can select a category to add to their routine.
Responses object in the task definition file
The responses object in the task definition file defines what statuses the task requester (in this case, the routine) can expect to receive when the task completes.
These statuses are similar to HTTP status codes. The following table shows responses statuses that are provided by default.
| Response Status | Description |
|---|---|
|
400 |
Indicates that the request failed a schema validation against the given task definition. For example, a lower limit is higher than an upper limit. |
|
403 |
Indicates that the requested task is denied access. |
|
404 |
Indicates that the requested task doesn't exist or no providers exist for the task. |
You can define your own statuses in the responses object of the task definition file. For example, for a count-down task, you might define statuses 200, 400, and 500, as shown in the following example.
{
"openapi": "3.0.0",
"info": {
"title": "A task to count down numbers",
"version": "1",
"x-amzn-alexa-access-scope": "public"
},
"tags": [{
"name": "count down"
}],
"paths": {
"/CountDown": {
"summary": "Count down",
"description": "Starts a countdown",
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Input"
}
}
}
},
"responses": {
"200": {
"description": "The countdown task finished successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessfulResponse"
}
}
}
},
"400": {
"description": "The given parameters fail validation. For example, lowerLimit is higher than upperLimit."
},
"500": {
"description": "The countdown task failed due to an internal error."
}
}
}
}
},
"components": {
"schemas": {
"Input": {
"type": "object",
"properties": {
"upperLimit": {
"type": "number",
"maximum": 100,
"minimum": 1
},
"lowerLimit": {
"type": "number",
"maximum": 100,
"minimum": 1
}
}
},
"SuccessfulResponse": {
"type": "object",
"properties": {
"endTime": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
Best practices for custom task parameters
You must protect your and your users' privacy and security. When you design custom tasks in routines, consider the following recommendations:
- Don't include custom-task parameter names or values that could reveal personally identifiable information (PII) for your users. PII data includes information like your user's name, address, email, and credit card numbers.
- The custom task description should clearly indicate what the task does and the input parameter description should indicate the expected input from the user. This way, the user can make an informed choice.
Related topics
- Understand Tasks
- Implement Custom Tasks in Your Skill
- Understand Skill Connections
- Create a Quick Link for Your Custom Task
Last updated: Sep 10, 2024