Integrate Your Custom Task 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.

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:

  1. The user enables the "My News" skill, either by using the Alexa app or by voice.
  2. In the Alexa app, the user goes to More > Routines.
  3. The user taps +.
  4. The user enters a routine name.
  5. The user taps When this happens, and then selects a trigger.
  6. 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.
    Alexa app task list for a My News skill, showing four options: Open My News, News Update, Stock Update, and News Category.
  7. 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.
    Task title display.
  8. 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 and Availability.
  • In the task definition file, you must set the x-amzn-alexa-access-scope field to public, not vendor-private.

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:

  1. Create a custom task.
  2. Choose locales.
  3. Update the task definition file.
  4. Validate your skill.
  5. 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.

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

  1. Log in to the developer console, and then navigate to your skill.
  2. At the top, click the Certification tab.
  3. Click Run.
  4. 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.

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:

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?

info.x-amzn-display-details.{locale}.title

Name for your custom task. The Alexa app displays this name to users in the specified locale.
Maximum length: 50 characters.

String

Yes

info.x-amzn-display-details.{locale}.description

Description of what your custom task can do. The Alexa app displays this description to users in the specified locale.
Maximum length: 250 characters.

String

Yes

info.x-amzn-alexa-access-scope

You must set this field to public.

String

Yes

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.

Confirmation screen for a News Update task that doesn't have any 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 minLength and maxLength to specify the minimum and maximum lengths of the string that the user can enter as the input parameter value. The value of minLength must be a positive integer. The value of maxLength must be greater than or equal to minLength. The default value of maxLength is 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?

info.x-amzn-display-details.{locale}.title

Name for your custom task. The Alexa app displays this name to users in the specified locale.
Maximum length: 50 characters.

String

Yes

info.x-amzn-display-details.{locale}.description

Description of what your custom task can do. The Alexa app displays this description to users in the specified locale.
Maximum length: 250 characters.

String

Yes

components.schemas.Input.properties.company.x-amzn-display-details.{locale}.name

Title for the input parameter.
Maximum length: 50 characters.

String

Yes

components.schemas.Input.properties.company.x-amzn-display-details.{locale}.description

Description of what the input parameter can do.
Maximum length: 250 characters.

String

Yes

info.x-amzn-alexa-access-scope

You must set this field to public.

String

Yes

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.

Input screen for a Stock update task, before user input, showing the prompt: Enter stock symbol.

When the user taps the prompt and then enters the stock symbol, the prompt disappears and the Alexa app displays the stock symbol.

Input screen for a Stock update task, after the user has entered AMZN as the stock symbol. The prompt is no longer shown.

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?

info.x-amzn-display-details.{locale}.title

Name for your custom task. The Alexa app displays this name to users in the specified locale.
Maximum length: 50 characters.

String

Yes

info.x-amzn-display-details.{locale}.description

Description of what your custom task can do. The Alexa app displays this description to users in the specified locale.
Maximum length: 250 characters.

String

Yes

components.schemas.Input.properties.enumName.x-amzn-display-details.{locale}.name

Title for the input parameter.
Maximum length: 50 characters.

String

Yes

components.schemas.Input.properties.enumName.x-amzn-display-details.{locale}.enums

List of resolvers for the enum defined for the task input.
Maximum length: 250 characters.

Object

Yes

components.schemas.Input.properties.enumName.x-amzn-display-details.{locale}.enums['{ENUM}']

Inputs that you define. Maximum length for a predefined input parameter: 50.

String

Yes

info.x-amzn-alexa-access-scope

You must set this field to public.

String

Yes

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.

News Category custom task offering four news categories.

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.