TemplateRuntime

    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.

    Version Changes

    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 execute directives without a dialogRequestId on a new thread.
      • Immediately execute 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.2 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.2"
    }
    

    RenderTemplate Directive

    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 Displays text-only title, subtitle, text, and skill icons. Wikipedia entries without images

    ASK simple cards
    BodyTemplate2 Displays body text and a single image. Wikipedia entries with images
    ListTemplate1 Displays lists and calendar entries. Shopping Lists

    To Do Lists

    Calendars
    LocalSearchDetailTemplate1
    (new)
    Displays individual location information for navigation-based points of interest. Navigation
    LocalSearchListTemplate2
    (new)
    Displays a list of navigation-based points of interest.

    When a user selects an item from this list, detail is rendered via the LocalSearchDetailTemplate1 template.
    Navigation
    TrafficDetailsTemplate
    (new)
    Displays travel distance and time. Navigation
    WeatherTemplate Displays 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 An image structure object containing the icon of the skill generating the content. This is an optional parameter which you can exclude from the JSON or include with a null value.  
    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 An image structure object containing the icon of the skill generating the content. This is an optional parameter which you can exclude from the JSON or include with a null value.  
    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 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 An image structure object containing the icon of the skill generating the content. This is an optional parameter which you can exclude from the JSON or include with a null value.  
    listItems A list of items or calendar entries. list
    listItems.leftTextField Left text field content. string
    listItems.rightTextField Right text field content. string

    LocalSearchDetailTemplate1

    LocalSearchDetailTemplate1 is a semantic template for rendering point of interest information for specific chain/entity name queries; for example: "Search for Starbucks nearby". The following illustrates an example display card rendered by the LocalSearchDetailTemplate1 template:

    BodyTemplate2
    Click to enlarge

    Sample Message

    {
      "directive": {
        "header": {
          "namespace": "TemplateRuntime",
          "name": "RenderTemplate",
          "messageId": "{{STRING}}",
          "dialogRequestId": "{{STRING}}"
        },
        "payload": {
          "token": "{{STRING}}",
          "type": "LocalSearchDetailTemplate1",
          "title": {
            "mainTitle": "{{STRING}}",
            "subTitle": "{{STRING}}"
          },
          "address": {{STRING}},
          "phoneNumber": {{STRING}},
          "provider": {{STRING}},
          "image": {{IMAGE_STRUCTURE}},
          "travelDistance": "{{STRING}}",
          "travelTime": "{{STRING}}",
          "offRouteTime": "{{STRING}}",
          "priceRange": "{{STRING}}",
          "url": "{{STRING}}",
          "rating": {
            "value": "{{STRING}}",
            "reviewCount": "{{STRING}}",
            "image": "{{IMAGE_STRUCTURE}}",
            "provider": "{{STRING}}" {
              "name": "{{STRING}}",
              "image": "{{IMAGE_STRUCTURE}}"
            },
          "coordinate": {
            "latitudeInDegrees": "{{DOUBLE}}",
            "longitudeInDegrees": "{{DOUBLE}}"
          },
          "currentStatus": {{STRING}},
          "travelDirection": {{STRING}},
          "hoursOfOperation": {
            "dayOfWeek": "{{STRING}}",
            "type": "{{STRING}}",
            "hours": {{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 Value Type
    token An opaque token provided by Alexa. string
    type Identifies the template; in this case, LocalSearchDetailTemplate1. string
    title An object containing the mainTitle/subTitle pair to be displayed on the card. object
    title.
      mainTitle
    The main title associated with the point of interest listing. string
    title.
      subTitle
    A list of all categories in which the point of interest specializes, in comma separated format. string
    address The address associated with the point of interest as given by the data provider. This may contain special characters, including a new line. string
    phoneNumber The phone number for the point of interest, in E.164 format. In addition to displaying the phone number, you can choose to make this a clickable link (or support a call icon) and implement calling. string
    provider A list of all the providers who contributed to this point of interest listing.

    Important! Including the list of providers who contributed to the point of interest listing on the template is a legal requirement which is enforced during the certification process.
    string
    image An image structure object containing a cover image associated with the point of interest. If the point of interest doesn't give a cover image, a default placeholder is used. object
    travelDistance The distance from the user's current location to the point of interest. string
    travelTime The travel time from the user's current location to the point of interest. string
    offRouteTime The increase in travelTime if the user adds this point of interest as a stop on a route that is currently being navigated. string
    priceRange The price range for the point of interest, as described by the data provider. This range is represented in formats specific to the data provider. For example, Yelp might provide the price range using currency symbols, while Zomata might use a phrase such as "price of two". string
    url The link to redirect the user to the website for the point of interest. You can use the url to make the point of interest image clickable. string
    rating An object containing the rating details for the point of interest, as given by the data provider. object
    rating.
      value
    The rating value for the point of interest, displayed in the format and scale specific to the data provider. string
    rating.
      reviewCount
    The number of reviews for the point of interest. string
    rating.
      image
    An image structure object containing the image that will be used to render the rating information for the point of interest. Different providers use different rating images, and the images are generated based on the rating value. object
    rating.
      provider
    An object that contains details about the provider that gave the rating. object
    rating.
      provider.
        name
    The name of the provider that gave the rating. string
    rating.
      provider.
        image
    An image structure object containing the logo for the provider that gave the rating. This is an optional parameter which you can exclude from the JSON or include with a null value. object
    coordinate An object containing the location information details associated with the point of interest. object
    coordinate.
      latitudeInDegrees
    The latitude, in degrees, corresponding to the location of the point of interest. double
    coordinate.
      longitudeInDegrees
    The longitude, in degrees, corresponding to the location of the point of interest. double
    currentStatus The current status of the point of interest. The client is responsible for localizing the point of interest status based on the local language.
    Accepted Values:
    OPEN
    CLOSED
    PERMANENTLY_CLOSED
    CLOSING_SOON
    string
    travelDirection An indication of where the point of interest is located in relation to the user's current location, based on the direction in which the user is currently traveling. If the cloud is unable to determine the user's current travel direction, this field is not initialized with a value.
    Accepted Values:
    AHEAD
    BEHIND
    string
    hoursOfOperation An object containing hours of operation details for the point of interest. object
    hoursOfOperation.
      dayOfWeek
    The day of the week to which the hoursOfOperation.type and hoursOfOperation.hours apply.
    Accepted Values:
    MONDAY
    TUESDAY
    WEDNESDAY
    THURSDAY
    FRIDAY
    SATURDAY
    SUNDAY
    string
    hoursOfOperation.
      type
    The hours of operation status type for the listed day of the week.
    Accepted Values:
    OPEN_DURING_HOURS: the location is open during the listed hours
    OPEN_24_HOURS: the location is open the entire day; do not list hours
    CLOSED: the location is closed for the day; do not list hours
    HOLIDAY: indicates days that may modify the location's schedule; you can display the available hours along with a note that "hours may vary"
    UNKNOWN: No hours of operation are known for this day
    string
    hoursOfOperation.
      hours
    The hours of operation for the listed day of the week. string

    LocalSearchListTemplate2

    LocalSearchListTemplate2 is a semantic template for rendering lists of points of interest in response to category queries; for example "Search for restaurants nearby". Based on the setting of the onInteraction parameter, touching a list item renders either the detail view provided by the LocalSearchDetailTemplate1 or navigation to that point of interest.

    The following illustrates an example display card rendered by the LocalSearchListTemplate2Template2 template:

    BodyTemplate2
    Click to enlarge

    Sample Message

    {
      "directive": {
        "header": {
          "namespace": "TemplateRuntime",
          "name": "RenderTemplate",
          "messageId": "{{STRING}}",
          "dialogRequestId": "{{STRING}}"
        },
        "payload": {
          "token": "{{STRING}}",
          "type": "LocalSearchListTemplate2",
          "onInteraction": "{{STRING}}",
          "title": {{STRING}},
          "sortType": {{ENUM}},
          "pointOfInterests" {
            "title" {
              "mainTitle": "{{STRING}}",
              "subTitle": "{{STRING}}"
            },
            "address": {{STRING}},
            "phoneNumber": {{STRING}},
            "provider": {{STRING}},
            "image": {{IMAGE_STRUCTURE}},
            "travelDistance": "{{STRING}}",
            "travelTime": "{{STRING}}",
            "offRouteTime": "{{STRING}}",
            "priceRange": "{{STRING}}",
            "url": "{{STRING}}",
            "rating": {
              "value": "{{STRING}}",
              "reviewCount": "{{STRING}}",
              "image": "{{IMAGE_STRUCTURE}}",
              "provider": "{{STRING}}" {
                "name": "{{STRING}}",
                "image": "{{IMAGE_STRUCTURE}}"
              },
            },
            "coordinate": {
              "latitudeInDegrees": "{{DOUBLE}}",
              "longitudeInDegrees": "{{DOUBLE}}"
            },
            "currentStatus": {{STRING}},
            "travelDirection": {{STRING}},
            "hoursOfOperation": {
              "dayOfWeek": "{{STRING}}",
              "type": "{{STRING}}",
              "hours": {{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 Value Type
    token An opaque token provided by Alexa. string
    type Identifies the template; in this case, LocalSearchListTemplate2. string
    onInteraction Identifies the action to be executed when the user touches a list item. This is an optional parameter which you can exclude from the JSON or include with a null value.
    Accepted Values:
    INITIATE_DETAIL_VIEW: load the detail card for the list item from the LocalSearchDetailTemplate1
    INITIATE_NAVIGATION: initiate navigation to the list item
    string
    title The title associated with the user's request; for example "Restaurants nearby" string
    sortType Indicates how the search results are sorted.
    Accepted Values:
    RATING_DESCENDING
    DISTANCE_ASCENDING
    PRICE_ASCENDING
    string
    pointOfInterests A list of items, rendered to the user with point of interest details. array
    title An object containing the title/subtitle pair to be displayed on the card. object
    title.
      mainTitle
    The main title associated with the point of interest listing. string
    title.
      subTitle
    The categories associated with the point of interest listing, in comma-separated format. This is an optional parameter which you can exclude from the JSON or include with a null value. string
    address The address associated with the point of interest, as given by the data provider. This may contain special characters, including a new line. string
    phoneNumber The phone number for the point of interest, in E.164 format. In addition to displaying the phone number, you can choose to make this a clickable link (or support a call icon) and implement calling. This is an optional parameter which you can exclude from the JSON or include with a null value. string
    provider A list of all the providers who contributed to this point of interest listing, in comma-separated format.

    Important! Including the list of providers who contributed to the point of interest listing on the template is a legal requirement which is enforced during the certification process.
    string
    image An image structure object containing a cover image associated with the point of interest. If the point of interest doesn't give a cover image, a default placeholder is used. object
    travelDistance The distance from the user's current location to the point of interest. string
    travelTime The travel time from the user's current location to the point of interest. string
    offRouteTime The increase in travelTime if the user adds this point of interest as a stop on a route that is currently being navigated. This is an optional parameter which you can exclude from the JSON or include with a null value. string
    priceRange The price range for the point of interest, as described by the data provider. This range is represented in formats specific to the data provider. For example, Yelp might provide the price range using currency symbols, while Zomata might use a phrase such as "price of two". This is an optional parameter which you can exclude from the JSON or include with a null value. string
    url The link to redirect the user to the website for the point of interest. You can use the url to make the point of interest image clickable. This is an optional parameter which you can exclude from the JSON or include with a null value. string
    rating An object containing the rating details for the point of interest, as given by the data provider. This is an optional parameter which you can exclude from the JSON or include with a null value. If you include rating, you must also include at least rating.value, rating.reviewCount, and rating.provider. object
    rating.
      value
    The rating value for the point of interest, displayed in the format and scale specific to the data provider. string
    rating.
      reviewCount
    The number of reviews for the point of interest. string
    rating.
      image
    An image structure object containing the image that will be used to render the rating information for the point of interest. Different providers use different rating images, and the images are generated based on the rating value. object
    rating.
      provider
    An object that contains details about the provider that gave the rating. object
    rating.
      provider.
        name
    The name of the provider that gave the rating. string
    rating.
      provider.
        image
    An image structure object containing the logo for the provider that gave the rating. This is an optional parameter which you can exclude from the JSON or include with a null value. object
    coordinate An object containing the location information details associated with the point of interest. object
    coordinate.
      latitudeInDegrees
    The latitude, in degrees, corresponding to the location of the point of interest. double
    coordinate.
      longitudeInDegrees
    The longitude, in degrees, corresponding to the location of the point of interest. double
    currentStatus The current status of the point of interest. The client is responsible for localizing the point of interest status based on the local language. This is an optional parameter which you can exclude from the JSON or include with a null value.
    Accepted Values:
    OPEN
    CLOSED
    PERMANENTLY_CLOSED
    CLOSING_SOON
    string
    travelDirection An indication of where the point of interest is located, in relation to the user's current location based on the direction in which the user is currently traveling. If the cloud is unable to determine the user's current travel direction, this field is not initialized with a value. This is an optional parameter which you can exclude from the JSON or include with a null value.
    Accepted Values:
    AHEAD
    BEHIND
    string
    hoursOfOperation An object containing hours of operation details for the point of interest. object
    hoursOfOperation.
      dayOfWeek
    The day of the week to which the hoursOfOperation.type and hoursOfOperation.hours apply. This is an optional parameter which you can exclude from the JSON or include with a null value.
    Accepted Values:
    MONDAY
    TUESDAY
    WEDNESDAY
    THURSDAY
    FRIDAY
    SATURDAY
    SUNDAY
    string
    hoursOfOperation.
      type
    The hours of operation status type for the listed day of the week.
    Accepted Values:
    OPEN_DURING_HOURS: the location is open during the listed hours
    OPEN_24_HOURS: the location is open the entire day; do not list hours
    CLOSED: the location is closed for the day; do not list hours
    HOLIDAY: indicates days that may modify the location's schedule; you can display the available hours along with a note that "hours may vary"
    UNKNOWN: No hours of operation are known for this day
    string
    hoursOfOperation.
      hours
    The hours of operation for the listed day of the week. string

    TrafficDetailsTemplate

    TrafficDetailsTemplate is a semantic template for rendering travel time and travel distance information.

    The following illustrates an example display card rendered by the TrafficDetailsTemplate template:

    BodyTemplate2
    Click to enlarge

    Sample Message

    {
      "directive": {
        "header": {
          "namespace": "TemplateRuntime",
          "name": "RenderTemplate",
          "messageId": "{{STRING}}",
          "dialogRequestId": "{{STRING}}"
        },
        "payload": {
          "token": "{{STRING}}",
          "type": "TrafficDetailsTemplate",
          "title": {
            "mainTitle": "{{STRING}}",
            "subTitle": "{{STRING}}"
          },
          "skillIcon": {{IMAGE_STRUCTURE}},
          "destinationInfo": {
            "label": "{{STRING}}",
            "address": "{{STRING}}"
          },
          "travelDistance": "{{STRING}}",
          "travelTime": "{{STRING}}",
          "currentTrafficConditionsImage": {{IMAGE_STRUCTURE}},
          "backgroundImage": {{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 Value Type
    token An opaque token provided by Alexa. string
    type Identifies the template; in this case, TrafficDetailsTemplate. string
    title An object containing key/value title information pair; for example, title/subtitle. The actual key/value pairs vary by template. object
    title.
      mainTitle
    The text to be displayed on the card's main title line (the key in the key/value title information pair). string
    title.
      subTitle
    The text to be displayed on the card's subtitle line (the value in the key/value title information pair). string
    skillIcon An image structure object containing the icon of the skill generating the content. This is an optional parameter which you can exclude from the JSON or include with a null value. object
    destinationInfo An object containing information about the destination such as travel time or travel distance. object
    destinationInfo.
      address
    The address of the destination, which can contain newline characters. string
    destinationInfo.
      label
    A user-supplied nickname for the destination; for example, "home" or "work". This is an optional parameter which you can exclude from the JSON or include with a null value. string
    travelDistance The travel distance and unit to the destination; for example, "2.7 miles". The Alexa device preference setting determines the unit. string
    travelTime The travel time to the destination. string
    currentTrafficConditionsImage An image structure object representing the current traffic conditions. This is an optional parameter which you can exclude from the JSON or include with a null value. object
    backgroundImage An image structure object representing the background image of the card. This is an optional parameter which you can exclude from the JSON or include with a null value. object

    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 An image structure object containing the icon of the skill generating the content. This is an optional parameter which you can exclude from the JSON or include with a null value.  
    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 Directive

    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.<p>Accepted values: BUTTON, TOGGLE. string
    controls.name The name of the control. All controls included in the array must be rendered.<p>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.

      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 execute directives without a dialogRequestId on a new thread.
        • Immediately execute 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"
      }
      

      RenderTemplate Directive

      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 Directive

      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.