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

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 registered 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

correlationToken

A token that identifies the message exchange. With the exception of discovery messages, a correlation token is included in the following message types:
  • A directive from Alexa to the skill.
  • An event in response to a directive.
A response event for a directive request should include the same correlation. If the event is not in response to a request from Alexa, a correlation token should not be provided.

messageID

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:
  • Alexa.PlaybackController
  • Alexa.ChannelController
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

scope

An polymorphic object that describes an aspect of the authentication granted to the message exchange. See scope object for more information.

endpointId

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.

cookie

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:00
    • 2016-09-13T20:11:32Z
    • 20160913T201132Z
  • 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