Implement Amazon Predefined Tasks in Your Skill

If you make your Alexa skill a provider skill, it can handle task requests from other skills that it receives through skill connections.

For more information about tasks and skill connections, see Understand Skill Connections.

A provider skill can implement one or more custom tasks, or it can implement Amazon-predefined tasks. This walkthrough covers Amazon predefined tasks. For custom tasks, see Implement Custom Tasks in Your Skill.

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.

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

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": "..."
    }
}

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.

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) {
        console.log("Handling AMAZON.PrintPDF task.");

        // Business Logic

        let speechText = "OK, your request has been received";

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

Response attributes

typeType of the directive. In this case, Tasks.CompleteTask is used to complete a task request.
statusContains 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",
    "originIpAddress": "string",
    "task": {
        "name": "AMAZON.PrintPDF",
        "version": "1",
        "input": {
            "@type": "PrintPDFRequest",
            "@version": "1",
            "title": "Flywheel",
            "description": "Flywheel",
            "url": "http://www.example.com/flywheel.pdf"
        }
    }
}

Example: cprovider 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

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

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

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

  1. Make sure that you have enabled testing in your provider skill. For more information, see Test your skill.
  2. In the Alexa Developer Console, open your provider skill, and then select the Test tab.
  3. 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 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.abcdef-0dff-4a56-a83c-9783ea111a11--AMAZON.PrintPDF
  4. 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.abcdef-0dff-4a56-a83c-9783ea111a11--AMAZON.PrintPDF

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.