Implement Amazon Predefined Tasks in Your Skill

Note: Sign in to the developer console to build or publish your skill.

A provider skill can implement one or more custom tasks, or it can implement Amazon-predefined tasks that other skills can request via direct skill connections. This walkthrough covers Amazon predefined tasks. For custom tasks, see Implement Custom Tasks in Your Skill.

Important: Currently only approved partners can implement Amazon predefined tasks.

The following list shows the current providers for Amazon predefined tasks:

Print: Hewlett-Packard, Canon, Epson
Book a table: OpenTable
Book a ride: Uber

Tasks to update your skill to become a provider for an Amazon predefined task

The following list shows the high-level process to update your skill to become a provider for an Amazon predefined task.

Update the skill manifest to register the skill as a provider for a task.
Implement a handler to fulfill a task.
Test your provider skill.
Publish your provider skill for certification.

Step 1: Update the skill manifest to register your skill as a provider for a task

To add Skill Connections support to your skill, add the tasks field to your skill manifest as shown in the following example.

The name field contains the name of the task that your skill is able to fulfill. The version field contains the version of that task. This example manifest indicates that this skill is registered to be a provider for version 1 of the AMAZON.PrintPDF task.

Example: skill manifest for a provider skill

The following example shows how to update the skill manifest to register your skill as a provider for a task.

{
   "manifest": {
       "publishingInformation": {
           "locales": { ... }
        },
       "apis": {
           "custom": {
               "endpoint": {
                   "uri": "..."
                },
               "interfaces": [],
               "tasks" : [
                    {
                     "name": "AMAZON.PrintPDF",
                     "version": "1"
                    }
                ]
            }
        },
       "manifestVersion": "..."
    }
}

Step 2: Implement a handler to fulfill a task

A provider skill implements a handler to fulfill a task.

After handling the task, the provider must send a Tasks.CompleteTask directive in response to signal task completion and communicate any information as the result of executing the task.

When your provider skill returns a Tasks.CompleteTask directive, the shouldSessionEnd attribute must be set to true.

Important: When responding to a request with a Tasks.CompleteTask or Connections.StartConnection directive, your response cannot include audio or video player directives.

Example: implement a handler that fulfills a task

The following example shows how to implement a handler to fulfill a task. This example shows an Amazon task.

const ConnectionsRequestHandler = {
    canHandle(handlerInput) {
        const request = handlerInput.requestEnvelope.request;
        return request.type === 'LaunchRequest'
            && request.task.name == "AMAZON.PrintPDF";
    },
    handle(handlerInput) {
        return handlerInput.responseBuilder
            .addDirective({
                "type": "Tasks.CompleteTask",
                "status": {
                    "code": "200",
                    "message": "Print succeeded"
                }
            })
            .withShouldEndSession(true)
            .getResponse();
    }
};

Response attributes

`type`	Type of the directive. In this case, `Tasks.CompleteTask` is used to complete a task request.
`status`	Contains code and message. Code can be any valid HTTP code.

Skill requester and provider code examples

The requester skill sends a task request to the provider skill.

Example: task request

{
    "type": "LaunchRequest",
    "requestId": "string",
    "timestamp": "string",
    "locale": "string",
    "task": {
        "name": "AMAZON.PrintPDF",
        "version": "1",
        "input": {
            "@type": "PrintPDFRequest",
            "@version": "1",
            "title": "Flywheel",
            "description": "Flywheel",
            "url": "http://www.example.com/flywheel.pdf"
        }
    }
}

Example: provider skill handles an `AMAZON.PrintPDF` task request

When the provider skill receives a task request, it must handle it if able to do so. This example shows how a provider skill might handle receiving an AMAZON.PrintPDF task request.

const PrintPDFTaskHandler = {
    canHandle(handlerInput) {
        const request = handlerInput.requestEnvelope.request;
        return request.type === 'LaunchRequest'
            && request.task.name == "AMAZON.PrintPDF";
    },
    handle(handlerInput) {
        console.log("Handling AMAZON.PrintPDF task.");

        // Logic to print PDF

        const speechText = "OK, your print is confirmed";

        return handlerInput.responseBuilder
            .speak(speechText)
            .addDirective({
                "type": "Tasks.CompleteTask",
                "status": {
                    "code": "200",
                    "message": "Print succeeded"
                }
            })
            .withShouldEndSession(true)
            .getResponse();
    }
};

Step 3: Test your provider skill

The ASK development team has provided a test requester skill that can send valid task requests to your provider skill. Follow these steps so that your provider skill can interact with this test requester skill. Make sure that you enter each of these commands on a single line. Currently, the test requester skill can only send Amazon predefined tasks.

To test your provider skill

Make sure that you have enabled testing in your provider skill. For details, see Test your skill.
In the Alexa Developer Console, open your provider skill, and then select the Test tab.
To test with a valid task request, enter:
open connection tester and send valid connection request with parameters <skill-id>--<task-name>
For <skill-id>, substitute your provider skill's skillId. For <task-name>, substitute a valid Amazon predefined task name such as AMAZON.PrintPDF. This command sends a request with a valid schema to your provider skill's development stage. For example, if you want to test how your provider skill handles the AMAZON.PrintPDF task, type:
open connection tester and send valid connection request with parameters amzn1.ask.skill.12345678-90ab-cdef-1234-567890abcdef--AMAZON.PrintPDF
To test with an invalid task request, enter:
open connection tester and send invalid connection request with parameters <skill-id>--<task-name>
This command sends a request with an invalid schema to your provider skill's development stage. For example, if you want to test how your provider skill handles the AMAZON.PrintPDF task with an invalid schema, type:
open connection tester and send invalid connection request with parameters amzn1.ask.skill.12345678-90ab-cdef-1234-567890abcdef--AMAZON.PrintPDF

Note: You can only use this override for the provider skillId in the development stage of your provider skill.

Step 4: Publish your provider skill for certification

After you finish testing your provider skill, you can publish your skill for certification. After Amazon certifies your skill, it becomes publicly available. When a requester sends a task request for the task that your skill provides, Alexa considers your provider skill as an option to fulfill the request.

To have your provider skill certified, it should meet the following behavioral requirements that help ensure a good customer experience.

Your provider skill must fulfill the task that the requester skill requested. For example, if your provider skill is supposed to print a web page, it must be able to do that when requested from the requester skill.
Your provider skill must gracefully handle an invalid or empty payload received from the requester skill. For example, if your provider skill is printing an image, and the URL provided for the image is invalid, the provider skill should inform the customer that the URL was invalid. If the payload is empty or invalid, your skill should handle this error gracefully with a user-friendly voice prompt.
The customer can cancel any actions that your provider skill fulfills on behalf of the requester skill by invoking the provider skill with the provider skill's example phrases or invocation name. The customer can do so just as if the customer had interacted with the skill directly. For example, with a ride-sharing provider skill, if the customer says "Alexa, cancel my ride", that utterance should lead to the same cancellation dialog as if the customer had ordered the ride directly from the skill.

Was this page helpful?

Provide feedback

Last updated: Sep 11, 2023