感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

Implement Alexa Skill Connections

With the Skill Connections feature, you can enable an Alexa skill to fulfill a customer request that it can't otherwise handle by forwarding the request to another skill for fulfillment. During a skill connection, the skill that asks Alexa for the fulfillment of a request is called the "requester" and the skill that services the request is called the "provider."

Skill Connections improve the Alexa customer experience by allowing customers to move freely between skills without having to repeat information. For example, a customer who interacts with a recipe skill can say "print this" to print a recipe with a web printing skill. If a skill connection fails, such as if a customer does not have a printer, the skill connection ends, and the customer is returned to the original requester skill session.

You can download sample code for a skill connection demo, which provides both requester and provider skill implementations. That sample code, and the example code provided in this document, uses the Alexa Skills Kit Node.js SDK.

Make your skill a skill connection requester

A "requester" skill requests a skill connection from a "provider" skill. If possible, the provider skill fulfills the request of the requester skill. You can modify your skill so that it becomes a requester, which means that it can request a skill connection from skills that are providers.

To make your skill a requester for a skill connections task

  1. Implement a handler to return a Connections.StartConnection directive.
  2. Implement a handler to receive the response from a skill connections request in the form of a SessionResumedRequest object. This is so the user returns to the same place in the original requester skill.

See the list of Supported skill connection tasks.

Implement handler to return Connections.StartConnection directive

Your skill can send a skill connections request if you set the Connections.StartConnection directive in the response object, as shown in the following example code. You must leave the shouldEndSession flag undefined when returning a Connections.StartConnection directive.

Example code to implement handler

return handlerInput.responseBuilder
        .addDirective({
            'type': 'Connections.StartConnection',
            'uri': 'connection://{task_name}{/version_number}',
            'input': {
                   ...
                }
            },
            'token': '...',
        })
        .getResponse();

Response attributes

typeType of the directive, which is Connections.StartConnection in this case.
uriResource that defines the task and the task version
inputContains the request object for the skill connection request being sent.
tokenToken comes back to the skill as-is in the SessionResumedRequest and can be used to resume the requester skill after the skill connection request is complete.

Implement handler to receive response from skill connections request

A requester skill must also implement a handler to receive a skill connection response for the original skill connection request. If you do not implement a response handler, then your skill will have an unhandled exception and that will break the customer experience.

To implement a handler to receive a skill connection response for a skill connection request

Add a SessionResumedRequest handler to the skill, as shown in the following example code.

When the requester skill receives a SessionResumedRequest, it restores the previous session of the skill from when the original Connections.StartConnection directive was returned.

Example code to implement response handler

const ConnectionsResponseHandler = {
  canHandle(handlerInput) {
    const request = handlerInput.requestEnvelope.request;
    return request.type === 'SessionResumedRequest';
  },
  handle(handlerInput) {
    const statusCode = handlerInput.requestEnvelope.request.cause.status.code;
    const statusMessage = handlerInput.requestEnvelope.request.cause.status.message;
    console.log('SessionResumedRequest received: status code : [' + statusCode + '], message : [' + message + ']');

   // Session attributes and ID are same as previous IntentRequest
   const sessionAttributes = handlerInput.attributesManager.getSessionAttributes();


    // Continue requester skill experience

    return handlerInput.responseBuilder
        .speak("Requester skill received SessionResumedRequest")
        .getResponse();
  },
};

Skill connection requester example

This example code shows how a skill might request the fulfillment of an Amazon.PrintPDF task.

First, a requester skill returns a Connections.StartConnection directive.

PrintPDFSkillConnectionsRequestDispatcher = {
    speechText: 'Requester sending Skill Connections request to print PDF',
    directive: {
        'type': 'Connections.StartConnection',
        'uri': 'connection://AMAZON.PrintPDF/1',
        'input': {
         '@type': 'PrintPDFRequest',
         '@version': '1',
         'title': 'title',
         'description': 'description',
         'url': 'http://www.example.com/flywheel.pdf'
        },
        'token': 'none'
    }

Then, after the skill connection request has been fulfilled by a provider skill, the requester receives a SessionResumedRequest object.

Here is the sample JSON schema for the request.

{
    "type": "SessionResumedRequest",
    "requestId": "string",
    "timestamp": "string",
    "locale": "string",
    "originIpAddress": "string",
    "cause": {
        "type": "ConnectionCompleted",
        "token": "1234",
        "status": {
            "code": "200",
            "message": "OK"
        },
        "result": null
    }
}

Here is example code for the SessionResumedRequest handler.

const SessionResumedRequestHandler = {
    canHandle(handlerInput) {
        const request = handlerInput.requestEnvelope.request;
        return request.type === 'SessionResumedRequest';
    },
    handle(handlerInput) {
        console.log("Requester skill received SessionResumedRequest");
        const sessionAttributes = handlerInput.attributesManager.getSessionAttributes();
        const status = handlerInput.requestEnvelope.request.cause.status;
        const code = status.code;
        const message = status.message;

        const speechText = `status code is ${code}, message is ${message}`;

        return handlerInput.responseBuilder
            .speak(speechText)
            .getResponse();
    },
};

Attributes

Any valid HTTP status code can be returned on a skill connection request call. Alexa will return any of the following status codes. However, the provider skill that is fulfilling the skill connection request can return any valid HTTP code.

  • status: Status of the request
    • code: status code
      • 200 : Request was successfully fulfilled
      • 204 : User denied to use the Connection
      • 227 : Provider was not account linked
      • 404 : No providers available at this time
      • 400 : Bad request - request was invalid
      • 500 : Server error
    • message : Plain string message describing the outcome of the request. For example - "Ride has been booked successfully."

For more information, see Handle Requests Sent by Alexa.

Test your requester skill

After you implement the necessary functionality to allow your skill to be a skill connection requester, you can test your skill as you would normally test for other invocations. Once you initiate the skill connection request, Alexa resolves a suitable provider for the skill connection request and the request is then routed to a live provider skill.

Additionally, you should test how your requester skill handles various status codes that may be returned to the requester skill during the handling of a skill connection request. To test how your skill responds when it receives a skill connection response with a specific status code, alter your requester skill to return a Connections.StartConnection directive with the AMAZON.TestStatusCode task defined. In the return body of this directive, the input includes the desired status code. For example, to test how your SessionResumedRequest handler deals with receiving a 502 status code, your skill should return the following directive:

return handlerInput.responseBuilder
        .addDirective({
            'type': 'Connections.StartConnection',
            'uri': 'connection://AMAZON.TestStatusCode/1',
            'input': {
                'code': '502'
            }
        })
        .getResponse();

Then, the requester skill receives a SessionResumedRequest object which contains the status code defined in the input.

Publish your requester skill

After you complete the testing and skill submission requirements, you can publish your skill to certification to receive skill connection tasks in a production environment. If your skill has already been certified, the changes will be live as soon as you publish them.

Make your skill a skill connection provider

Update your skill to become a provider for a skill connection task

  1. Update the skill manifest to register the skill as a provider for a skill connection task.
  2. Implement a handler to fulfill a skill connection task.

In addition, your skill must be approved as a provider during the certification process.

Update the skill manifest to register your skill as a provider for a skill connection task

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

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

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

Implement a handler to fulfill a skill connection task

A provider skill must implement a handler to receive a skill connection request. If you do not implement a request handler, then your skill will have an unhandled exception and that will break the customer experience.

The provider skill receives a LaunchRequest object in the request sent from the requester skill.

After handling the task, the provider must send a Tasks.CompleteTask directive in response to return control back to the requester. When your provider skill returns a Tasks.CompleteTask directive, the shouldSessionEnd attribute must be defined as true.

Example code to implement a handler

const ConnectionsRequestHandler = {
    canHandle(handlerInput) {
        const request = handlerInput.requestEnvelope.request;
        return request.type === 'LaunchRequest'
            && request.task.name == "AMAZON.RequestType";
    },
    handle(handlerInput) {
        console.log("Handling AMAZON.RequestType 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 skill connection request.
statusContains code and message. Code can be any valid HTTP code.

Provider skill code example

Here is an example of a LaunchRequest object that might be received by the skill connection request handler.

{
    "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 code

This example code shows how a provider skill might handle receiving an Amazon.PrintPDF skill connection 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 Alexa Skills Kit development team has provided a testing skill that can send valid skill connection requests to your provider skill. Follow these steps to interact with this testing skill. Make sure you enter a command on a single line.

  1. Make sure that you have enabled testing in your provider skill. For more information, see Test your skill.
  2. Open your provider skill in the developer console, and click the Test tab.
  3. To test with a valid skill connection request, type:
    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 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 PrintPDF task, type:
    open connection tester and send valid connection request with parameters amzn1.ask.skill.abcdef-0dff-4a56-a83c-9783ea111a11--PrintPDF
  4. To test with an invalid skill connection request, type:
    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 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--PrintPDF

Publish your provider skill for certification

When you finish testing your provider skill, you can publish your skill for certification. Once certified, your skill becomes live. When a requester sends a skill connection request for the task that your skill provides, Alexa considers your skill as an option to fulfill the request.

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

  • Your provider skill must fulfill the functionality related to the skill connection task that the requester skill invoked. Thus, 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.
  • Any actions that your provider skill fulfills on behalf of the requester skill can be cancelled by invoking the provider skill with the provider skill's example phrases or invocation name, 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 should lead to the same cancellation dialog as if the customer had ordered the ride directly from the skill.

Supported skill connection tasks

Skill Connections support the following tasks. Each task has a unique schema for its payload.

To provide a consistent user experience, each skill connection task has its own voice design guidelines, which are included with the description of each task. These guidelines indicate the prompts used by the requester skill, the provider skill, and Alexa during the fulfillment of a skill connection request.

AMAZON.PrintImage

The AMAZON.PrintImage task enables your skill to send an image to a printing skill. This task can be used for printing photos, coloring pages, puzzles, origami templates, and so forth.

Parameters

Name Required? Type Description
title Yes String Title of what is being printed
description No String Description of the file
url Yes String URL of the image
imageType Yes String {JPG, JPEG} Type of image

Sample response with input

{
  "type": "Connections.StartConnection",
  "uri": "connection://AMAZON.PrintImage/1",
  "input": {
         "@type": "PrintImageRequest",
         "@version": "1",
         "title": "Flywheel Document",
         "description": "Flywheel",
         "imageType": "JPEG",
         "url": "http://www.example.com/flywheel.jpeg"
  }
}

Voice design guidelines

This example demonstrates an expected customer experience for the AMAZON.PrintImage task.

Alexa (as determined by requester skill developer): Today's crossword puzzle is available!
Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?
User: Sure.
Alexa (as determined by provider skill developer): Today's crossword puzzle is now printing.
Alexa (as determined by Alexa): Returning you to {requester_skill_name}.

During the transition from the requesting skill to the provider skill, Alexa always renders prompts similar to those provided here. Thus, your skill does not need to render similar prompts.

Customer has never used provider Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?
Customer has used provider Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?

When the session transitions from the provider skill back to the requester skill, Alexa renders a prompt to indicate this.

Alexa (as determined by Alexa): Returning you to {requester_skill_name}.

When your skill surfaces a piece of content that the customer might like to print, your skill should return a response which includes:

  • A prompt that tells the customer that the content is available.
  • A Connections.StartConnection directive with the relevant payload parameters.

AMAZON.PrintPDF

The AMAZON.PrintPDF task enables your skill to send a PDF document to a printing skill. The possible uses for this task are very broad, and include printing documents, coloring pages, puzzles, origami templates, and so forth.

Parameters

Name Required? Type Description
title Yes String Title of what is being printed
description No String Description of the PDF file
url Yes String Location of the PDF file

Sample response with input

{
 "type": "Connections.StartConnection",
 "uri": "connection://AMAZON.PrintPDF/1",
 "input": {
         "@type": "PrintPDFRequest",
         "@version": "1",
         "title": "title",
         "description": "description",
         "url": "http://www.example.com/flywheel.pdf"
  }
}

Voice design guidelines

This example demonstrates an expected customer experience for the AMAZON.PrintPDF task.

Alexa (as determined by requester skill developer): Today's crossword puzzle is available!
Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?
User: Sure.
Alexa (as determined by provider skill developer): Today's crossword puzzle is now printing.
Alexa (as determined by Alexa): Returning you to {requester_skill_name}.

During the transition from the requesting skill to the provider skill, Alexa always renders prompts similar to those provided here. Thus, your skill does not need to render similar prompts.

Customer has never used provider Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?
Customer has used provider Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?

When the session transitions from the provider skill back to the requester skill, Alexa renders a prompt to indicate this.

Alexa (as determined by Alexa): Returning you to {requester_skill_name}.

When your skill surfaces a piece of content that the customer might like to print, your skill should return a response which includes:

  • A prompt that tells the customer that the content is available.
  • A Connections.StartConnection directive with the relevant payload parameters.

AMAZON.PrintWebPage

The AMAZON.PrintWebPage task enables your skill to send a web page to a printing skill. The possible uses for this task are very broad, and include printing documents, coloring pages, puzzles, origami templates, and so forth.

Name Required? Type Description
title Yes String Title of what is being printed
description No String Description of the web page
url Yes String Location of the web page

Sample response with input

{
 "type": "Connections.StartConnection",
 "uri": "connection://AMAZON.PrintWebPage/1",
 "input": {
       "@type": "PrintWebPageRequest",
       "@version": "1",
       "title": "title",
       "description": "description",
       "url": "http://www.example.com/flywheel.html"
    }
}

Voice design guidelines

This example demonstrates an expected customer experience for the AMAZON.PrintWebPage task.

Alexa (as determined by requester skill developer): Today's crossword puzzle is available!
Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?
User: Sure.
Alexa (as determined by provider skill developer): Today's crossword puzzle is now printing.
Alexa (as determined by Alexa): Returning you to {requester_skill_name}.

During the transition from the requesting skill to the provider skill, Alexa always renders prompts similar to those provided here. Thus, your skill does not need to render similar prompts.

Customer has never used provider Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?
Customer has used provider Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?

When the session transitions from the provider skill back to the requester skill, Alexa renders a prompt to indicate this.

Alexa (as determined by Alexa): Returning you to {requester_skill_name}.

When your skill surfaces a piece of content that the customer might like to print, your skill should return a response which includes:

  • A prompt that tells the customer that the content is available.
  • A Connections.StartConnection directive with the relevant payload parameters.

AMAZON.ScheduleTaxiReservation

The AMAZON.ScheduleTaxiReservation task should be used by skills to help customers book rides. This task enables a skill to use the customer's preferred method of scheduling rides, thus making the requester skill more useful, and driving business to the provider.

Name Required? Type Description
partySize No integer Number of people in the reservation
pickupLocation Yes/No PostalAddress Optional only when dropoffLocation is provided. Location where the customer wants to be picked up.
pickupTime No dateTime Time at which the customer wants to be picked up.
dropoffLocation Yes/No PostalAddress Optional only when pickupLocation is provided. Location where the customer wants to be dropped off.

PostalAddress Parameters

Name Required? Type Description
streetAddress Yes String Street address
locality Yes string Typically a town or city or equivalent.
region Yes string Typically a state or province or equivalent.
postalCode Yes String Postal code, which is a zip code in the United States.
country No string Country

Sample response with input

{
 "type": "Connections.StartConnection", 
 "uri": "connection://AMAZON.ScheduleTaxiReservation/1",
 "input": {
       "@type": "ScheduleTaxiReservationRequest",
       "@version": "1",
       "partySize": 4,
       "pickupLocation": {
           "@type": "PostalAddress",
           "@version": "1",
           "streetAddress": "415 106th Ave NE",
           "locality": "Bellevue",
           "region": "WA",
           "postalCode": "98004",
           "country": "US"
        },
       "pickupTime": null,
       "dropoffLocation": {
           "@type": "PostalAddress",
           "@version": "v",
           "streetAddress": "2031 6th Ave.",
           "locality": "Seattle",
           "region": "WA",
           "postalCode": "98121",
           "country": "US"
        }
    }
}

Voice design guidelines

The example below depicts the expected customer experience for the AMAZON.ScheduleTaxiReservation task.

Alexa (as determined by requester skill developer): Your tickets have been booked.
Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?
User: Sure.
Alexa (as determined by provider skill developer): {ride_fulfilling_skill}
Alexa (as determined by Alexa): Returning you to {requester_skill_name}.

During the transition from the requesting skill to the provider skill, Alexa always renders prompts similar to those provided here. Thus, your skill does not need to render similar prompts.

Customer has never used provider Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?
Customer has used provider Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?

When the session transitions from the provider skill back to the requester skill, Alexa renders a prompt to indicate this.

Alexa (as determined by Alexa): Returning you to {requester_skill_name}.

When your customer has completed something and you believe that ordering a ride would be relevant, your skill should return a response which includes:

  • A prompt that tells the customer they have completed something.
  • A Connections.StartConnection directive with the relevant input parameters.

AMAZON.ScheduleFoodEstablishmentReservation

The AMAZON.ScheduleFoodEstablishmentReservation task should be used by restaurant-related skills to help customers get reservations. This task enables a skill to use the customer's preferred method of scheduling restaurant reservations, thus making the requester skill more useful, and driving business to the restaurant.

Name Required? Type Description
startTime No dateTime Time of the reservation
partySize No number Number of people in the reservation
restaurant Yes Restaurant Restaurant where reservation is placed

Restaurant Parameters

Name Required? Type Description
name Yes string Name of the restaurant
location Yes PostalAddress Address of the restaurant

PostalAddress Parameters

Name Required? Type Description
streetAddress Yes String Street address
locality Yes string Typically a town or city or equivalent.
region Yes string Typically a state or province or equivalent.
postalCode Yes String Postal code, which is a zip code in the United States.
country No string Country

Sample response with input

{
 "type": "Connections.StartConnection",
 "uri": "connection://AMAZON.ScheduleFoodEstablishmentReservation/1",
 "input": {
       "@type": "ScheduleFoodEstablishmentReservationRequest",
       "@version": "1",
       "startTime": "2018-04-08T01:15:46Z",
       "partySize": 2,
       "restaurant": {
           "@type": "Restaurant",
           "@version": "1",
           "name": "Amazon Day 1 Restaurant",
           "location": {
               "@type": "PostalAddress",
               "@version": "1",
               "streetAddress": "2121 7th Avenue",
               "locality": "Seattle",
               "region": "WA",
               "postalCode": "98121",
               "country": "US"
            }
        }
    }
}

Voice design guidelines

This example demonstrates an expected customer experience for the AMAZON.ScheduleFoodEstablishmentReservation task.

Alexa (as determined by requester skill developer): Bytes to Eat has the best hip cocktails near you.
Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?
User: Sure.
Alexa (as determined by provider skill developer): {provider_skill}
Alexa (as determined by Alexa): Returning you to {requester_skill_name}.

During the transition from the requesting skill to the provider skill, Alexa always renders prompts similar to those provided here. Thus, your skill does not need to render similar prompts.

Customer has never used provider Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?
Customer has used provider Alexa (as determined by Alexa): Do you want to give {provider_skill_name} a try?

When the session transitions from the provider skill back to the requester skill, Alexa renders a prompt to indicate this.

Alexa (as determined by Alexa): Returning you to {requester_skill_name}.

After a customer has prompted about a restaurant and you would like to offer to reserve a table for them, your skill should return a response which includes:

  • A prompt that tells the customer know about the restaurant.
  • A Connections.StartConnection directive with the relevant input parameters.