Integrate Your Custom Task with Alexa Routines

You can integrate custom tasks with Alexa Routines to provide customers with richer experiences and drive more traffic to your skills. Additionally, you can reuse a custom task that you create for Alexa Routines integration in skill connections and quick links.

This page describes how to make your skill's tasks available to users as Alexa routine actions.

What are Alexa routines and actions?

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 utterance, like "Alexa, start my Morning Session." The sequence of actions is a list of tasks for Alexa to perform when the trigger happens, for example, delivering a news briefing and then telling the weather forecast. Users can enable built-in Alexa routines or create their own custom routines by choosing triggers and routine actions 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 it to their custom routines.

How do skills and tasks appear in the Alexa app?

When you define and publish a custom task and integrate it with Alexa Routines, the task appears in your skill as a routine action that the user can choose when creating a custom routine in the Alexa app.

When users enable your skill in the Alexa app, the skill's custom tasks are displayed as routine actions when the user taps Add action > Skills > {Your skill}. The following screenshot shows a skill called "My News", with three custom tasks that are listed as routine actions.

Alexa app task list for My News skill, showing 3 tasks: Open My News, News update, and Stock quote
Alexa app task list for My News skill

Integrate a custom task with Alexa Routines

If you haven't already done so, build a custom task in your skill following the instructions in Implement Custom Tasks in Your Skill.

To make your custom tasks available to Alexa Routines, you'll need to supply user-friendly strings for your task title, task description, input parameter name and description so that they can be displayed to customers in the Alexa app.

To supply these strings, add them to the task definition file as follows.

  1. First, determine where you plan 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. Make sure your skill is published in those locales.

  2. For each locale, provide the following information in the appropriate language. The task title and description fields are always required. The task input parameter name and description are only required if your task has an input parameter.

    • Task title and description – The x-amzn-display-details field of the info object is a custom extension field to add user-friendly strings and localization mappings for your task. In this field, enter the task title and description to be displayed in the Alexa app.
    • Input parameter name and description – The x-amzn-display-details field in the paths object is a custom extension field to add user-friendly strings and localization mappings for your task's input parameter. In this field, enter the task input parameter name and description to be displayed in the Alexa app.

Restrictions on integrating tasks with Alexa Routines

  • In the developer preview phase, Amazon only supports custom tasks with no input parameters or with a single string input parameter.
  • In the task definition file:
    • The x-amzn-alexa-access-scope field must be set to public, not vendor-private.
    • You can use optional fields minLength and maxLength to specify the minimum and maximum lengths of the string the end user can enter as input parameter values. 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.
  • Your task must be a custom task, not an Amazon predefined task.
  • Your task must be live (certified and published) and available in each desired marketplace. For details, see Develop Skills in Multiple Languages and Define Skill Store Details and Availability.
  • In the developer preview phase, versioning isn't supported.
  • Because the Alexa app allows users to enter arbitrary strings for your input parameters, your task must gracefully handle any unexpected text input. For example, if the user enters text input that your task doesn't support, Amazon recommends using a default value.

Example: task definition for custom task without input parameters

The following example shows a task definition for a "News update" custom task that provides news updates. This task doesn't have any task input parameters. To enable it for Alexa Routines integration, 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": {}
        },
        "response": {
            ...
        }
      }
    }
  }
}

The user-friendly strings you supply in the info object are displayed to users in the Routines action list in the Alexa app. In this case, there are no input parameters, so when the user chooses "News update" from the action list, they are taken to a confirmation screen. Note that the Alexa app uses a template to display the string: Alexa will open ${task title}, where the task title is the user-friendly string extracted from the x-amzn-display-details.title field of the info object.

The following screenshot shows a confirmation screen for a "News update" task that has no parameters.

Confirmation screen for News update task
Confirmation screen for News update task

Example: task definition for custom task with a string input parameter

The following example shows a "Stock update" custom task that provides stock price updates. Like the "News update" custom task, this task has x-amzn-display-details field contains user-friendly strings for the task title and description to enable it for Alexa Routines integration. In addition, this task requires a single string input parameter: the company name. 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",
        "discription": "Provide stock price updates"
      },
      "es-US": {
        "title": "Actualización de stock",
        "description": "Proporcionar actualizaciones de precios de acciones"
      }
    }
  },
  "paths": {
    "/StockQuote": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company": {
                    "type": "string",
                    "x-amzn-display-details": {
                      "en-US": {
                        "name": "Company name",
                        "description": "Enter stock symbol"
                      },
                      "es-US": {
                        "name": "Nombre de empresa",
                        "description": "Ingrese el símbolo de stock"
                      }
                    }
                  }
                }
              }
            }
          }
        }
        "responses": {
          ...
        }
      }
    }
  }
}

In this case, the action contains a string input parameter, so when the user chooses "News update" from the action list, they are taken to a screen with a text input field. The user-friendly string that you supply in the x-amzn-display-details.description of the paths object is displayed as the hint text for the input field.

The following screenshot shows an input screen for a "Stock quote" task that has a single parameter. The prompt "Enter stock symbol" is displayed.

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

When the user taps the prompt and enters the stock symbol, the prompt disappears and only the stock symbol is displayed.

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

Make your custom task available by publishing your skill

The process for making a custom task available to Alexa Routines is the same as that for making a custom task available for skill connections. Your skill must be certified and published to make your custom tasks available. Once your integrated skill has been published to the live stage, its custom tasks are available as actions in Alexa Routines.

You can specify which locales to surface your custom tasks in by providing user-friendly task title and description strings for those specific locales in the x-amzn-display-details field of the info object. If the task title and description of a given locale is missing from the task definition, the task won't be available in Alexa Routines in that locale.

Best practices: Custom task parameters

To protect your customers' privacy and security using tasks in your skill, and to provide the best user experience, consider the following recommendations:

  • Don't include custom task parameter names or values that could reveal personally identifiable information (PII) for your customers. PII data includes things like your customer's name, address, email, and Social Security numbers.
  • Your custom task's input parameter descriptions should provide clear instructions to help Alexa Routines users enter valid text input.