TemplateRuntime 1.0


The TemplateRuntime interface provides visual metadata to AVS-enabled products with GUI support. These display cards are used to describe or enhance a user's voice interactions. Metadata is provided as structured JSON and should be bound to templates that adhere to design guidelines for each supported device type.

For screen-specific design guidance, see UX Design Overview.

Data flow

This diagram illustrates the high-level message flow for delivering visual metadata to an AVS-enabled product.

Data flow diagram.
Click to enlarge
  1. A user asks, "Who is Usain Bolt?". Their speech is captured by your product and streamed to AVS.
  2. AVS returns two directives:
    • A Speak directive that instructs your client to play Alexa TTS.
    • A RenderTemplate directive that instructs your client to display visual metadata – in this case, information about Usain Bolt.
  3. Playback of Alexa TTS starts.
  4. The RenderTemplate directive is rendered immediately (and if possible, in tandem with the Speak directive) in a separate thread.
  5. Your client informs AVS that your product has started to playback Alexa TTS by sending a SpeechStarted event.
  6. When playback of Alexa TTS finishes, a SpeechFinished event is sent to AVS.

Rendering visual metadata

In addition to the guidance provided in the Interaction Model, these rules must be enforced by your product when rendering visual metadata:

  • Read the response on the request thread and parse the directives:
    • Immediately run directives without a dialogRequestId on a new thread.
    • Immediately run RenderTemplate directives on a new thread.
    • Place directives with a dialogRequestId in your queue.
  • Directives in the queue should be picked up on a separate thread and handled sequentially.
  • Play directives and associated RenderPlayerInfo directives must be in sync. Unlike RenderTemplate, the directive should not always be rendered immediately, but should match the sequence of Play directives. For example, after sending PlaybackNearlyFinished, if you receive a new Play directive and RenderPlayerInfo directive these must be added to the queue and handled when the currently playing track has finished. This means that display card implementation must be aware of playback state, such as playing, stopped, or paused.

Capability assertion

TemplateRuntime 1.0 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.

New AVS integrations must assert support through Alexa.Discovery, but Alexa will continue to support existing integrations using the Capabilities API.

Sample Object

{
    "type": "AlexaInterface",
    "interface": "TemplateRuntime",
    "version": "1.0"
}

Directives

RenderTemplate

The Render directive instructs your client to display visual metadata associated with a user's request. For example, when a user asks Alexa, "Who is Usain Bolt?". In addition to sending a   Speak directive, AVS will send a Render directive with visual metadata that your client will bind to a template and render for the end user.

The following templates are currently supported:

Type Description Use Cases
BodyTemplate1 A text only template that supports title, subtitle, text and skill icons. Wikipedia entries without images, ASK simple cards
BodyTemplate2 A template with support for body text and a single image. Wikipedia entries with images.
ListTemplate1 A template for lists and calendar entries. Shopping Lists, To Do Lists, Calendars
WeatherTemplate A template designed to display weather data. Weather

BodyTemplate1

BodyTemplate1 is used to render text-only visual metadata. The following illustrates a sample Wikipedia entry:

BodyTemplate1
Click to enlarge

Sample Message


{
  "directive": {
    "header": {
      "namespace": "TemplateRuntime",
      "name": "RenderTemplate",
      "messageId": "{{STRING}}",
      "dialogRequestId": "{{STRING}}"
    },
    "payload": {
      "token": "{{STRING}}",
      "type": "BodyTemplate1",
      "title": {
        "mainTitle": "{{STRING}}",
        "subTitle": "{{STRING}}"
      },
      "skillIcon": {{IMAGE STRUCTURE}},
      "textField": "{{STRING}}"         
    }
  }
}

Header Parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. string
dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

Payload Parameters

Parameter Description Type
token An opaque token provided by Alexa. string
type Identifies the template. In this example, type is set to BodyTemplate1. string
title Contains key/value pairs for title information, such as title and subtitle. Actual key/value pairs vary by template. object
title.mainTitle The title. string
title.subTitle The subtitle. string
skillIcon The icon/logo for the skill delivering metadata. This is an optional parameter for the content provider and may not be included in the JSON (or may have a null value). The image structure contains information such as url, size, widthPixels and heightPixels. For more information, see image structure below. image structure
textField Body text for the card. string

BodyTemplate2

BodyTemplate2 is used to render body text and a single image. The following illustrates a sample Wikipedia entry:

BodyTemplate2
Click to enlarge

Sample Message


{
  "directive": {
    "header": {
      "namespace": "TemplateRuntime",
      "name": "RenderTemplate",
      "messageId": "{{STRING}}",
      "dialogRequestId": "{{STRING}}"
    },
    "payload": {
      "token": "{{STRING}}",
      "type": "BodyTemplate2",
      "title": {
        "mainTitle": "{{STRING}}",
        "subTitle": "{{STRING}}"
      },
      "skillIcon": {{IMAGE_STRUCTURE}},
      "textField": "{{STRING}}",
      "image": {{IMAGE_STRUCTURE}},       
    }
  }
}

Header Parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. string
dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

Payload Parameters

Parameter Description Type
token An opaque token provided by Alexa. string
type Identifies the template. In this example, type is set to BodyTemplate1. string
title Contains key/value pairs for title information, such as title and subtitle. Actual key/value pairs vary by template. object
title.mainTitle The title. string
title.subTitle The subtitle. string
skillIcon The icon/logo for the skill delivering metadata. This is an optional parameter for the content provider and may not be included in the JSON (or may have a null value). The image structure contains information such as url, size, widthPixels and heightPixels. For more information, see image structure below. image structure
textField Left-aligned body text. string
image Right-aligned body image. image structure

ListTemplate1

ListTemplate1 is used to render lists (to-do lists, shopping lists) and calendar entries. The following examples illustrate a sample to-do list and calendar entries:

ToDo List

ListTemplate1
Click to enlarge

Calendar

ListTemplate1
Click to enlarge

Sample Message


{
  "directive": {
    "header": {
      "namespace": "TemplateRuntime",
      "name": "RenderTemplate",
      "messageId": "{{STRING}}",
      "dialogRequestId": "{{STRING}}"
    },
    "payload": {
      "token": "{{STRING}}",
      "type": "ListTemplate1",
      "title": {
        "mainTitle": "{{STRING}}",
        "subTitle": "{{STRING}}"
      },
      "skillIcon": {{IMAGE_STRUCTURE}},
      "listItems": [
        {
          "leftTextField": "{{STRING}}",
          "rightTextField": "{{STRING}}"
        },
        {
          "leftTextField": "{{STRING}}",
          "rightTextField": "{{STRING}}"
        },
        {
          ...
        }
      ]         
    }
  }
}

Header Parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. string
dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

Payload Parameters

Parameter Description Type
token An opaque token provided by Alexa. string
type Identifies the template. In this example, type is set to BodyTemplate1. string
title Contains key/value pairs for title information, such as title and subtitle. Actual key/value pairs vary by template. object
title.mainTitle The title. string
title.subTitle The subtitle. string
skillIcon The icon/logo for the skill delivering metadata. This is an optional parameter for the content provider and may not be included in the JSON (or may have a null value). The image structure contains information such as url, size, widthPixels and heightPixels. For more information, see image structure below. image structure
listItems A list of items or calendar entries. list
listItems.leftTextField Left text field content. string
listItems.rightTextField Right text field content. string

WeatherTemplate

WeatherTemplate is a semantic template for rendering the weather forecast.

WeatherTemplate
Click to enlarge

Sample Message


{
  "directive": {
    "header": {
      "namespace": "TemplateRuntime",
      "name": "RenderTemplate",
      "messageId": "{{STRING}}",
      "dialogRequestId": "{{STRING}}"
    },
    "payload": {
      "token": "{{STRING}}",
      "type": "WeatherTemplate",
      "title": {
        "mainTitle": "{{STRING}}",
        "subTitle": "{{STRING}}"
      },
      "skillIcon": {{IMAGE_STRUCTURE}},
      "currentWeather": "{{STRING}}",
      "description": "{{STRING}}",
      "currentWeatherIcon": {{IMAGE_STRUCTURE}},
      "highTemperature": {
        "value": "{{STRING}}",
        "arrow": {{IMAGE_STRUCTURE}}
      },
      "lowTemperature": {
        "value": "{{STRING}}",
        "arrow": {{IMAGE_STRUCTURE}}
      },
      "weatherForecast": [
        {
          "image": {{IMAGE_STRUCTURE}},
          "day": "{{STRING}}",
          "date": "{{STRING}}",
          "highTemperature": "{{STRING}}",
          "lowTemperature": "{{STRING}}"
        },
        {
          "image": {{IMAGE_STRUCTURE}},
          "day": "{{STRING}}",
          "date": "{{STRING}}",
          "highTemperature": "{{STRING}}",
          "lowTemperature": "{{STRING}}"
        },
        {
          ...
        }
      ]
    }
  }
}

Header Parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. string
dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

Payload Parameters

Parameter Description Type
token An opaque token provided by Alexa. string
type Identifies the template. In this example, type is set to BodyTemplate1. string
title Contains key/value pairs for title information, such as title and subtitle. Actual key/value pairs vary by template. object
title.mainTitle The title. string
title.subTitle The subtitle. string
skillIcon The icon/logo for the skill delivering metadata. This is an optional parameter for the content provider and may not be included in the JSON (or may have a null value). The image structure contains information such as url, size, widthPixels and heightPixels. For more information, see image structure below. image structure
currentWeather Current temperature for the date requested. string
description Description of the current weather conditions. string
currentWeatherIcon Image for current weather. image structure
highTemperature An object containing temperature and image metadata. object
hightemperature.value High temperature for the date requested. string
hightemperature.arrow Arrow image to render alongside temperature. image structure
lowTemperature An object containing temperature and image metadata. object
lowTemperature.value Low temperature for the date requested. string
lowTemperature.arrow Arrow image to render alongside temperature. image structure
weatherForecast Provides weather metadata for X days from the date requested. list
weatherForecast.image Representation of weather conditions. image structure
weatherForecast.day Provides day of the week. For example, "Mon" or "Tue". string
weatherForecast.date Provides the date. Date follows ABBR_MONTH_DAY format. For example, "Oct 22". string
weatherForecast.highTemperature Provides the high temperature for the associated date. string
weatherForecast.lowTemperature Provides the low temperature for the associated date. string

RenderPlayerInfo

The RenderPlayerInfo directive instructs your client to display visual metadata associated with a media item, such as a song or playlist. In addition to sending a   Play directive, AVS will send a RenderPlayerInfo directive with visual metadata specific to an audio content provider that your client will bind to a template and render for the end user.

This example illustrates playback from Amazon Music:

PlayerInfo
Click to enlarge

Sample Message


{
  "directive": {
    "header": {
      "namespace": "TemplateRuntime",
      "name": "RenderPlayerInfo",
      "messageId": "{{STRING}}",
      "dialogRequestId": "{{STRING}}"
    },
    "payload": {
      "audioItemId": "{{STRING}}",
      "content": {
        "title": "{{STRING}}",
        "titleSubtext1": "{{STRING}}",
        "titleSubtext2": "{{STRING}}",
        "header": "{{STRING}}",
        "headerSubtext1": "{{STRING}}",
        "mediaLengthInMilliseconds": {{LONG}},   
        "art": {{IMAGE_STRUCTURE}},     
        "provider": {
          "name": "{{STRING}}",
          "logo": {{IMAGE_STRUCTURE}}
        }                
      }
      "controls": [
        // This array includes all controls that must be
        // rendered on-screen.
        {
          "type": "{{STRING}}",
          "name": "{{STRING}}",
          "enabled": {{BOOLEAN}},
          "selected": {{BOOLEAN}}
        },
        {
          "type": "{{STRING}}",
          "name": "{{STRING}}",
          "enabled": {{BOOLEAN}},
          "selected": {{BOOLEAN}}
        },
        {
          ...
        }
      ]
    }
  }
}

Header Parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. string
dialogRequestId A unique ID used to correlate directives sent in response to a specific Recognize event. string

Payload Parameters

Parameter Description Type
audioItemId Identifies the audioItem. This parameter should be used to correlate the provided visual metadata with a Play directive. string
content Contains key/value pairs for title information, such as title and subtitle. Actual key/value pairs vary by template. object
content.title The title. string
content.titleSubtext1 The first text field. string
content.titleSubtext2 The second text field. string
content.header The first header text field. string
content.headerSubtext1 The second header text field. string
content.mediaLengthInMilliseconds The stream duration in milliseconds. long
content.art Artwork for provided audio item. image structure
content.provider Contains information about the content provider. object
content.provider.name Content provider's name. string
content.provider.logo Content provider's logo. image structure
controls A list of buttons that must be displayed on-screen. list
controls.type Identifies the control type. Accepted values: BUTTON, TOGGLE. string
controls.name The name of the control. All controls included in the array must be rendered. Accepted values: PLAY_PAUSE, NEXT, PREVIOUS, SKIP_FORWARD, SKIP_BACKWARD, SHUFFLE, LOOP, THUMBS_UP, THUMBS_DOWN. string
controls.enabled Informs the client if the control is clickable. The value is true when the control can be clicked by the user. boolean
controls.selected Indicates that a control should render in a selected state. For example, if a user has favorited a song, when this song plays, the control that represents favorite will have a selected value of true. boolean

Control to Event Mapping

When a user interacts with an on-screen control an event must be sent to Alexa using the PlaybackController interface. This table maps controls to the events in the PlaybackController interface that must be sent:

Control Type Control Name Event Notes
BUTTON PLAY_PAUSE PlayCommandIssued n/a
BUTTON NEXT NextCommandIssued n/a
BUTTON PREVIOUS PreviousCommandIssued n/a
BUTTON SKIP_FORWARD ButtonCommandIssued The control is specified in the event payload.
BUTTON SKIP_BACKWARD ButtonCommandIssued The control is specified in the event payload.
TOGGLE SHUFFLE ToggleCommandIssued The control is specified in the event payload.
TOGGLE LOOP ToggleCommandIssued The control is specified in the event payload.
TOGGLE THUMBS_UP ToggleCommandIssued The control is specified in the event payload.
TOGGLE THUMBS_DOWN ToggleCommandIssued The control is specified in the event payload.

Image Structure


{
  "contentDescription": "{{STRING}}",
  "sources": [
    {
      "url": "{{STRING}}",
      "darkBackgroundUrl": "{{STRING}}",
      "size": "{{STRING}}",
      "widthPixels": {{LONG}},
      "heightPixels": {{LONG}}
    },
    {
      ...
    },
    {
      ...
    }
  ]
}

Parameter Description Type
contentDescription Describes the image. This is an optional parameter for the content provider and may not be included in the JSON. string
sources A list of sources for the same image. It may contain url, size, widthPixels and heightPixels. It's important to note that this is a list and there may be a single or multiple sources. list
sources[i].url The image URL. This is always included in the JSON. string
sources[i].darkBackgroundUrl The image URL for night mode assets. These images are optimized for use with dark backgrounds. This is an optional parameter from the service. Click here for additional information. string
sources[i].size The image size as an enumerated value. This is an optional parameter for the content provider and may not be included in the JSON. If widthPixels and/or heightPixels are not provided, render to the specification provided below. Accepted values: X-SMALL, SMALL, MEDIUM, LARGE and X-LARGE. string
sources[i].widthPixels Image width in pixels. This is an optional parameter for the content provider and may not be included in the JSON. long
sources[i].heightPixels Image height in pixels. This is optional parameter for the content provider and may not be included in the JSON. long

Image Size Specifications

Provides each supported enumeration of size.

Value Description
X-SMALL Displayed within x-small containers.
SMALL Displayed within small containers.
MEDIUM Displayed within medium containers.
LARGE Displayed within large containers.
X-LARGE Displayed within x-large containers.

Was this page helpful?

Last updated: Nov 27, 2023