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.
Field | Description | Data Type |
---|---|---|
scope required |
Scope of the request. Includes token and type properties.
|
Object |
token required |
An OAuth2 bearer token
Example: |
String |
type required |
The type of the scope. The current supported value is BearerToken .
Example: |
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
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: |
String |
type required |
The type of the scope. The current supported value is BearerToken .
Example: |
Enum |
version optional |
Indicates the interface version that this endpoint supports.
Example: |
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: |
Object |
extraDetail optional |
Keys for the cookie object.
Example: |
|
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: |
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: |
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: |
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: |
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… |