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
  • Request Example
  • Response Example
• Header object
• Endpoint object
  • Scope object
• Context object
• Payload object
  • Discovery Directives and Events
  • Other Directives and Events
• 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:

• Header
• Endpoint
• Payload

In addition, some events contain:

• Context

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:

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.

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.

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
      }
    ]
  }

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.

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