Message and Data Formats for Video Skills
When you work with the Video Skill API, messages, dates, times and URIs have a common format. This document describes these formats.
- Request/Response Messages
- Authentication
- Directive and Event Format
- Header object
- Endpoint object
- Context object
- Payload object
- Date and Time Format
Request/Response Messages
Alexa sends your skill directives messages that request something on behalf of the customer. The directives include authentication data for the customer as well as a payload that communicates what they requested.
You respond with an Alexa.Response or an error message event that is relevant to the request and why it failed.
Authentication
The Video Skill API follows the OAuth2.0 specification. Every request sent from the Video Skill API to a skill adapter contains an OAuth access token in the request. In addition, the device cloud for any cloud-enabled device must support the authorization code grant flow type.
Make sure that you have whitelisted the OAuth redirect endpoint assigned to your video skill with our OAuth provider. You can find these URLs listed as the Redirect URLs on the Account linking page for your skill on the developer console. Also, the OAuth provider must have a certificate signed by an Amazon-approved certificate authority.
For more information about authenticating a customer and account linking in Alexa, see Understand Account Linking.
Directive and Event Format
Directives sent to your skill and events sent by your skill back to the Alexa, share the same basic structure. Directive and events contain the following top-level objects:
In addition, some events contain:
The endpoint and header objects are shown and described in the following examples and table.
The contents of the payload will vary depending on the type of message identified in the header. For payload details, see the documentation for the type of message you are sending, such as discovery or playback control
Request Example
Following is a request example for a change channel request.
{
"directive": {
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "some-access-token"
},
"endpointId": "appliance-001",
"cookie": {}
},
"header": {
"messageId": "47971513-5e09-4c5f-826b-d1c2b75800a7",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"name": "ChangeChannel",
"namespace": "Alexa.ChannelController",
"payloadVersion": "3"
},
"payload": {
"channel": {
"affiliateCallSign": "KBTC",
"callSign": "KBTC",
"channelImage": "http://s3.amazonaws.com/channel_images/pbs.png",
"name": "PBS",
"number": "123"
}
}
}
}
Response Example
{
"context": {
"properties": []
},
"event": {
"header": {
"messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3"
},
"endpoint":{
"scope":{
"type":"DirectedUserId",
"userId":"some-Amazon-user-id"
},
"endpointId":"videoDevice-001"
},
"payload": { }
}
}
Header object
A header has a set of expected fields that are the same across message types. These provide different types of identifying information. Following is an example of a typical message header:
"header": {
"messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3"
}
A header can contain the following properties:
| Property | Description |
|---|---|
|
|
A token that identifies the message exchange. With the exception of discovery messages, a correlation token is included in the following message types:
|
|
|
A unique identifier for a single request or response. This is used for tracking purposes and your skill should log this information, although it should not be used to support business logic. Every message must have this field populated. Any string of alphanumeric characters and dashes less than 128 characters is valid, but a version 4 UUID, which is a UUID generated from random numbers, is recommended. |
name
|
The name of the directive such as TurnOn or TurnOff
|
namespace
|
A string that specifies the category for the message payload. This aligns to the interface that contains that directive. Namespaces are used to group together common API methods. In addition, you can use the namespace value to route the message. For example:
|
payloadVersion
|
The API version that should be applied to the payload message. The version covered in this, and related documents, is 3. |
Endpoint object
An endpoint object identifies the device to communicate with. In addition, the endpoint contains an authentication token to enable the communication with the device.
Following is an example JSON for a typical message endpoint:
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "the identifier of the target endpoint",
"cookie": {
"key1": "some information",
"key": "value pairs received during discovery"
}
},
An endpoint object sent with a directive will contain the following properties.
| Property | Description |
|---|---|
|
|
An polymorphic object that describes an aspect of the authentication granted to the message exchange. See scope object for more information. |
|
|
A device identifier. The identifier must be unique across all devices owned by an end user within the domain for the skill. This identifier is provided initially during device discovery, and should consistently identify this device associated with this user. |
|
|
A list of key/value pairs associated with the endpoint. These are provided during discovery and are sent in each message for an endpoint. |
Scope object
A scope is a polymorphic object that provides authorization and identifying info for this message. A scope contains a type field and an additional key/value pair that vary depending on the type. The following table describes the types supported.
Scope type value |
Description | Associated field and description |
|---|---|---|
BearerToken |
Provides an OAuth bearer token for accessing a linked customer account. | token in the format: "token" : "atc|tokenvalue" |
DirectedUserId |
Currently not used, but element should be present. A placeholder field for the identifier of the account associated with Alexa. | directedUserId in the format: "directedUserId" : "someID" |
Context object
Use the Context object to report state in the event message returned for a ChangeChannel directive. A context contains an array of property objects and their state according to one of the property schemas. When you send a response event with context, you should ensure that the values reported incorporate all the side-effects from handling the directive. In other words, the property values reported must be after any value-changing side effects of handling the directive.
Following is an example context for an endpoint that implements the Alexa.ChannelController interface.
"context": {
"properties": [
{
"namespace": "Alexa.ChannelController",
"name": "channel",
"value": {
"number": 1234,
"callSign": "callsign1",
"affiliateCallSign": "callsign2"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
| Field | Description |
|---|---|
namespace |
Specifies the interface for the property |
name |
The property name being reported |
timeOfSample |
The time at which the property value was sampled, specified in UTC. A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. |
uncertaintyInMilliseconds |
Indicates the uncertainty of the reported property in milliseconds of elapsed time since the property value was retrieved. For example, if you obtain this value by polling a hardware device every 60 seconds, then the uncertainty in the time of the sampled value would be 60000 in milliseconds. |
Payload object
The payload for a directive or event depends on the name of the directive specified in the header. Payload directive and event contents are described in detail in each capability interface topic.
Discovery Directives and Events
The first step for a video skill is to enable discovery of customer devices and report the capabilities that the skill can control for the devices. Messages for a discovery request and response are slightly different than other message types. See Alexa.Discovery for more details on discovery message formats.
Other Directives and Events
The individual interface topics describe the payload of directives and events related to controlling devices or services.
| Operation | Capability Interface |
|---|---|
| Change the channel on a device | Alexa.ChannelController |
| Control the playback of device; fast forward, rewind and pause | Alexa.PlaybackController |
| Launch an app or a shortcut | Alexa.Launcher |
| Record the video content currently playing | Alexa.RecordController |
| Schedule a video content recording | Alexa.VideoRecorder |
| Seek a specific place in a video | Alexa.SeekController |
| Search for and play video content | Alexa.RemoteVideoPlayer |
| Indicate an error has occurred | Generic errors: Alexa.ErrorResponse Video-specific errors: Alexa.Video.ErrorResponse |
Date and Time Format
Message dates and times are strings in ISO 8601 format.
For Example:
- Date Only:
2016-09-13 - Combined date and time in UTC:
2016-09-13T20:11:32+00:002016-09-13T20:11:32Z20160913T201132Z
- Combined date and time in PDT:
2016-09-13T20:11:32-07:00 - Week:
2016-W37 - Date with week number:
2016-W37-2 - Date without year :
--09-13 - Ordinal date:
2016-257
