Thank you for your visit. This page is only available in English at this time.

Discovery Directives (VSK MM)

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

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
Indicates the interface version that this endpoint supports.

Example: 1.0

String
cookie
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
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…