Create a Quick Link for Your Custom Task

You can generate a Quick Link to take your customers to a specific custom task within your custom skill and pass input parameters. For example, you can deep-link customers to a new trivia category in a trivia skill, or to new audio content that you just made available. If your skill can track a customer's online orders with your business using an order ID, you can pass the order ID from your website to your skill through a Quick Link and start tracking the order for the customer using your skill.

Quick Links for custom tasks have the same requirements and availability as Quick Links for custom skills, plus a few additional ones:

  • Devices: Customers can use Quick Links to launch skills on these devices: Echo (all versions), Echo Tap, Echo Dot (all versions), Echo Show (all versions), Echo Spot
  • Locales: Custom skills that are built for en_US, es_US

Your skill must meet the following requirements:

  • Child-directed skills and HIPAA skills aren't eligible to use Quick Links.

Your custom task must meet the following requirements:

  • It must be a custom task, not an Amazon predefined task.
  • It must be live (certified and published).
  • In the task definition file:
    • The x-amzn-alexa-access-scope field must be set to public, not vendor-private.
    • The components.schemas.Input object must contain at least one input parameter.

Create your custom task

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 enable Quick Links, you'll need to add the following information to the task definition file:

  • A user-friendly name for the task, for example: "Count down"
  • A short description of what the task does, for example: "Start counting down"

This information is displayed on the Amazon page customers see when they click your custom task's Quick Link.

The URL for a custom task's Quick Link has the following syntax: https://alexa-skills.amazon.com/apis/custom/skills/<skill-id>/tasks/<custom-task-name>/versions/<task-version>?<task-input-key1>=<task-input-value1>&<task-input-key2>=<task-input-value2>

Name Required? Type Description
skill-id Yes String The skill ID for your skill.
custom-task-name Yes String Internal name of your custom task
task-version Yes String Version number for your custom task
task-input-key1 No String Name of the first parameter for your custom task
task-input-value1 No String Value of the first parameter for your custom task

To generate Alexa custom task link for your live custom task

  1. Locate the skill-id for your live custom skill:
    1. Navigate to the Alexa developer console.
    2. Log in if necessary.
    3. In the Skills tab, click the View Skill ID link under the skill name.
  2. Add your skill ID to the URL.
  3. Add your custom task name and version.

If your custom task requires <task-input-key> = <task-input-value> input parameter-value pairs, you can include them as a standard URL query string. Task parameters must be simple data types, such as strings, numbers, or Boolean values.

Add campaign attribution to your traffic analytics

You can track the number of skill launches coming from individual links surfaced in different online channels, by using input parameters in custom tasks in your skill, in combination with query string parameters in the Quick Link URL.

Your skill can capture traffic analytics for individual ad campaigns that you run online, for example on different social media channels. To do so, create an input parameter with the name a2z_ref in each custom task in your skill that you want to surface as a Quick Link. You can use this parameter in your Quick Link URL as a query string parameter and set its value to be a unique string that you can attribute to a particular source. While you are free to create any input parameter you like, and use it to pass attribution strings, the a2z_ref input parameter exists only for campaign attribution and doesn't appear in the Quick Links web page.

Here are the steps you need to follow to add campaign attribution to your traffic analytics.

To add attribution parameters to your Quick Links

  1. Follow the steps listed here to create a custom task in your skill. Or you can use an existing custom task if you have one.
  2. In the task definition file for the custom task, create an input parameter named a2z_ref, of type string.
  3. Implement functionality for this task in your skill's handler code. If you simply want to offer your launch experience to your customer, you only need to add a new check to your LaunchRequest handler's can_handle logic that checks if this is a request for your custom task. Following is an example in Python:
   def can_handle(self, handler_input): 
   return is_request_type("LaunchRequest")(handler_input)\ 
   and handler_input.request_envelope.request.task.name == "<your task name>"
  1. Publish your skill to make your new or modified custom task live.
  2. Once your custom task is live, you can compose a Quick Link for this task, include the a2z_ref parameter in the URL, and assign it values depending on the campaign where it will be surfaced online, for example, like an ad campaign.

When customers click this Quick Link to launch your skill, the request will carry the value of the a2z_ref parameter as an input parameter to your custom task, which you can then use for attributing the launch to the corresponding campaign.

Custom Task Parameters – Best Practices

While custom tasks enhance the functionality of your Quick Links by supporting deep linking, it is important to protect privacy and security for both you and the customers using your skill. When designing custom task parameters and generating Quick Links for these tasks, refer to the following recommendations:

  • Select the right data type for your input parameter. For example, if your input parameter is always going to have a numeric value, pick a numeric data type for the parameter when defining your task.
  • If possible, enumerate the values that you will use with your input parameters rather than accepting free-form strings. You can then reject any values coming in from Quick Link query strings that don’t map to this enumeration. This prevents misuse of your Quick Link query parameters by malicious actors.
  • When using the a2z_ref attribution parameter, use a predefined string pattern that works for your marketing team. Reject any values that don't match this pattern. For example, your pattern could be <website-or-app-name>_<campaign>, where <website-or-app-name> is a string that represents the name of the website or app where you will surface the link, and campaign is a string that represents a name that you come up with for your marketing campaign. By requiring your marketers to always use this pattern, including the underscore, you will be able to validate the input value that you receive in your custom task handler logic.
  • Do not include parameter names or values that could reveal Personally Identifying Information (PII) for your customers. PII data includes things like your customer's name, address, email, and Social Security numbers.
  • In some cases, you may wish to pass encoded values in the URL parameter and decode them in your custom task handler logic. When you do this, make sure you indicate through your input parameter description string that this is an encoded value. For example, say you want to encode a discount offer id and pass it as a parameter in your custom task URL that you later decode in your handler logic before rendering the customer experience. For the custom task input parameter, choose a human-readable name like "Secret Offer Id". This allows the customer to see something like this on the amazon.com page: "Secret Offer Id: a1b2c3", helping them understand that this value shouldn't be visible, while also protecting both your customer and your skill.