Discovery Directives (VSK Echo Show)

Amazon sends a Discover directive through the Discovery API to determine what capabilities your video skill supports. Your response to the Discovery directive determines what types of directives Alexa will send to your Lambda function.

For example, if you indicate support for channel changing, Alexa will send GetPlayableItems directives with type": "Channel" payloads when users say Change the channel to PBS. But if you don't indicate this support, Alexa won't send the directive.

Discovery Directives
Discover Example
Payload Description
Example Response
Payload Description
Capabilities Object

Discovery Directives

Alexa sends a Discovery directive after the user associates an Alexa skill with their Amazon account; after that, Alexa periodically sends Discovery directives to update any discovered devices.

When you receive a Discover directive, you must specify the directives your skill supports. You indicate the supported operations through the supportedOperations array.

(Note that with Fire TV implementations, you also indicated your capabilities support in your Android app when you initializing the Alexa Client Library. With multimodal implementations, you only need to indicate your support in your Lambda function.)

Discover Example

The following is an example Discover directive that Alexa sends.

{
    "directive": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover",
            "payloadVersion": "3",
            "messageId": "a1dccea0-fe52-45ca-9ed9-a03a45be6fb6"
        },
        "payload": {
            "scope": {
                "type": "BearerToken",
                "token": "1bdaa2eb-4aa3-d0dc-fb10-7a5513981cf8"
            }
        }
    }
}

Payload Description

The following table describes the payload fields.

Payload Descriptions
Field	Description	Data Type
`scope` required	Scope of the request. Includes `token` and `type` properties.	Object
`token` required	An OAuth2 bearer token Example: `b68f05cc-6a25-4134`	String
`type` required	The type of the scope. The current supported value is `BearerToken`. Example: `BearerToken`	Enum

Example Response

The following is an example response (Discover.Response) to a Discover directive. The response indicates which operations are supported.

{
"event": {
    "header" : {
        "messageId" : "directive.header.messageId",
        "name" : "Discover.Response",
        "namespace": "Alexa.Discovery",
        "payloadVersion": "3"
    },
    "payload": {
      "endpoints": [{
              "endpointId": "ALEXA_VOICE_SERVICE_EXTERNAL_MEDIA_PLAYER_VIDEO_PROVIDER",
              "endpointTypeId": "TEST_VSK_MM",
              "manufacturerName": "TEST_VSK_MM",
              "friendlyName": "TEST_VSK_MM",
              "description": "TEST_VSK_MM",
              "displayCategories": ["APPLICATION"],
              "cookie": {},
              "capabilities": [{
                      "type": "AlexaInterface",
                      "interface": "Alexa.RemoteVideoPlayer",
                      "version": "1.0"
                  }, {
                      "type": "AlexaInterface",
                      "interface": "Alexa.PlaybackController",
                      "version": "1.0"
                  }, {
                      "type": "AlexaInterface",
                      "interface": "Alexa.SeekController",
                      "version": "1.0"
                  }, {
                      "type": "AlexaInterface",
                      "interface": "Alexa.ChannelController",
                      "version": "1.0"
                  },
                  {
                      "type": "AlexaInterface",
                      "interface": "Alexa.MultiModalLandingPage",
                      "version": "1.0"
                  }
              ]
          }]
        }
}
};

Payload Description

Payload Descriptions
Field	Description	Data Type
`endpoints` required	An array of endpoint objects that represents the devices associated with a customer’s device cloud account.	Object
`capabilities` required	The capability interfaces that your skill supports for the endpoint. See the Capabilities Object below for more detail.	An array of capability objects
`interface` required	The qualified name of the `Alexa.Interface` that describes the actions for the device. Example: `Alexa.RemoteVideoPlayer`	String
`type` required	The type of the scope. The current supported value is `BearerToken`. Example: `BearerToken`	Enum
`version` optional	Indicates the interface version that this endpoint supports. Example: `1.0`	String
`cookie` optional	String name/value pairs that provide additional information about a device for use by the skill adapter. The contents of this property cannot exceed 5000 bytes. (Amazon doesn't use this field nor will customers see the value you put. However, you cannot enter the same value as your video skill name.) Example: `key1`	Object
`extraDetail` optional	Keys for the `cookie` object. Example: `key1`
`description` required	The description of the device. The description should might contain your company name or implementation. This value can contain up to 128 characters. (Amazon doesn't use this field nor will customers see the value you put. However, you cannot enter the same value as your video skill name.) Example: `Amazon Streaming Media App`	String
`endpointId` required	The identifier for the endpoint. For example, `VSKTV`. Note: You cannot enter the same value as your video skill name. It's also recommended that you preface the value with `TEST_` or `PROD_` to ensure that it's unique from your video skill name. Example: `TEST_VSKTV`	String
`friendlyName` required	This name identifies the type of implementation for the video skill. This value can contain up to 128 characters and should not contain special characters or punctuation. Note: Do not enter the same value as your video skill name. For example, if your video skill's name is "ACME Media," do not also enter "ACME Media" for the friendly name. Doing so will result in an error. Preface the name with something like "TEST_ACME_Media" or "PROD_ACME_Media". Example: `TEST_VSK_FTV`	String
`manufacturerName` required	The name of the manufacturer of the device. This value can contain up to 128 characters. (Amazon doesn't use this field nor will customers see the value you put. However, you cannot enter the same value as your video skill name.) Example: `Amazon`	String

Capabilities Object

The capabilities array can have a list of objects that each contain an interface, type, version, and supportOperations properties. For example, an item in a capabilities array declaring support for playback capabilities might look as follows:

{
    "type": "AlexaInterface",
    "interface": "Alexa.PlaybackController",
    "version": "3",
    "supportedOperations" : ["Play", "Pause", "Stop", "StartOver", "Next", "Previous",
      "Rewind", "FastForward"]
}

The Alexa.PlaybackController interface is the only interface that includes a supportedOperations property.

The following table describes the supported capabilities for video skills and the related directives:

Capability	Description
`Alexa.RemoteVideoPlayer`	Your skill can support `SearchAndPlay` and `SearchAndDisplayResults` directives. These directives allow users to search and play video content. For example, "Search for Breaking Bad" or "Alexa, watch Breaking Bad."
`Alexa.PlaybackController`	Your skill can support Playback Control directives that are used to play, stop, and navigate playback for audio or video content. For example, "Alexa, fast forward" or "Alexa, stop." Note that the `Alexa.PlaybackController` interface also allows a `supportedOperations` property as shown above. Allowed properties are `Play`, `Pause`, `Stop`, `StartOver`, `Next`, `Previous`, `Rewind`, `FastForward`.
`Alexa.SeekController`	Your skill can support Seek Control directives that allow the user to navigate to a specific position on the media timeline through requests such as "Alexa, fast-forward 60 seconds" or "Alexa, skip back 5 minutes" (as opposed to "Alexa, fast-forward" or "Alexa, rewind") (If your app can only fast-forward or rewind a media item, not seek to another point in the timeline, implement the `Alexa.PlaybackController` interface instead.)
`Alexa.ChannelController`	Your video skill can support `ChangeChannel` directives, which are used to change or increment the channel for an entertainment device. For example, "Alexa, change the channel to PBS."
`Alexa.MultiModalLandingPage`	Your video skill can support populating a landing page. For example, when users say "Video Home" and then tap on your video skill, your skill shows a list of videos…