TemplateRuntime 1.3
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
- New parameters to the
WeatherTemplate
- Added the
currentWeatherIconCode
parameter to represent the current weather icon. See currentWeatherIconCode mapping. - Added the
weatherForecast.iconCode
parameter to represent the forecast icon. See weatherForecast.iconCode mapping.
- Added the
Data flow
This diagram illustrates the high-level message flow for delivering visual metadata to an AVS-enabled product.

- A user asks, "Who is Usain Bolt?". Their speech is captured by your product and streamed to AVS.
- 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.
- A
- Playback of Alexa TTS starts.
- The
RenderTemplate
directive is rendered immediately (and if possible, in tandem with theSpeak
directive) in a separate thread. - Your client informs AVS that your product has started to playback Alexa TTS by sending a
SpeechStarted
event. - 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.
- Immediately run directives without a
- Directives in the queue should be picked up on a separate thread and handled sequentially.
Play
directives and associatedRenderPlayerInfo
directives must be in sync. UnlikeRenderTemplate
, the directive should not always be rendered immediately, but should match the sequence ofPlay
directives. For example, after sendingPlaybackNearlyFinished
, if you receive a newPlay
directive andRenderPlayerInfo
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" }
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 | 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 - for automotive products only) |
Displays individual location information for navigation-based points of interest. | Navigation |
LocalSearchListTemplate2 (new - for automotive products only) |
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 - for automotive products only) |
Displays travel distance and time. | Navigation |
WeatherTemplate | Displays weather data. | Weather |
type
has unique payload parameters specific to the content your client must render.BodyTemplate1
BodyTemplate1
is used to render text-only visual metadata. The following illustrates a sample Wikipedia entry:

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:

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

Calendar

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
was created solely to fill a gap for automotive products. If you are developing a non-automotive product, use TemplateRuntime 1.0.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:

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
was created solely to fill a gap for automotive products. If you are developing a non-automotive product, use TemplateRuntime 1.0.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:

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 run 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
was created solely to fill a gap for automotive products. If you are developing a non-automotive product, use TemplateRuntime 1.0.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:

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.

Sample Message
{% raw %} { "directive": { "header": { "namespace": "TemplateRuntime", "name": "RenderTemplate", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "type": "WeatherTemplate", "title": { "mainTitle": "{{STRING}}", "subTitle": "{{STRING}}" }, "skillIcon": {{IMAGE_STRUCTURE}}, "description": "{{STRING}}", "currentWeather": "{{STRING}}", "currentWeatherIcon": {{IMAGE_STRUCTURE}}, "currentWeatherIconCode": {{INTEGER}}, "highTemperature": { "value": "{{STRING}}", "arrow": {{IMAGE_STRUCTURE}} }, "lowTemperature": { "value": "{{STRING}}", "arrow": {{IMAGE_STRUCTURE}} }, "weatherForecast": [ { "iconCode": {{INTEGER}}, "image": {{IMAGE_STRUCTURE}}, "day": "{{STRING}}", "date": "{{STRING}}", "highTemperature": "{{STRING}}", "lowTemperature": "{{STRING}}" }, { "iconCode": {{INTEGER}}, "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 |
currentWeatherIconCode | ID code of each weather forecast icon. | integer. See currentWeatherIconCode mapping. |
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 |
weatherForecast.iconCode | ID code of each weather forecast icon. | integer. See weatherForecast.iconCode mapping. |
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:

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
source.url
. All other fields are optional for content providers, however, your client should be prepared to handle these fields if present. Please Note: sources
is a list of images and it is possible for this list to be a single source or multiple sources for the same image. There is no guarantee that multiple sources will be provided.{ "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. |
currentWeatherIconCode map
Provides the mapping of the current weather text and its corresponding icon code.
Current weather condition string | Icon code (Integer) |
---|---|
"clear skies and sun" |
1 |
"mostly sunny skies" |
2 |
"partly sunny skies" |
3 |
"intermittent clouds" |
4 |
"sun and haze" |
5 |
"mostly cloudy skies" |
6 |
"cloudy skies" |
7 |
"dreary skies" |
8 |
"fog" |
11 |
"showers" |
12 |
"showers and mostly cloudy skies" |
13 |
"showers and partly cloudy skies" |
14 |
"thunderstorms" |
15 |
"thunderstorms and mostly cloudy skies" |
16 |
"thunderstorms and partly sunny skies" |
17 |
"rain" |
18 |
"flurries" |
19 |
flurries and mostly cloudy skies" |
20 |
"flurries and partly sunny skies" |
21 |
"snow" |
22 |
"snow and clouds" |
23 |
"ice" |
24 |
"sleet" |
25 |
"freezing rain" |
26 |
"rain and snow" |
29 |
"hot weather" |
30 |
"cold weather" |
31 |
"windy weather" |
32 |
"clear skies" |
33 |
"mostly clear skies" |
34 |
"partly cloudy skies" |
35 |
"intermittent clouds" |
36 |
"hazy skies" |
37 |
"mostly cloudy skies" |
38 |
"showers and partly cloudy skies" |
39 |
"showers and mostly cloudy skies" |
40 |
"thunder showers and partly cloudy skies" |
41 |
"thunder showers and mostly cloudy skies" |
42 |
"flurries and mostly cloudy skies" |
43 |
"snow fall and mostly cloudy skies" |
44 |
weatherForecast.iconCode map
Provides the mapping of the weather forecast text and its corresponding icon code.
Daily weather forecast string | Icon code (Integer) |
---|---|
"lots of sun" |
1 |
"mostly sunny weather" |
2 |
"partly sunny weather" |
3 |
"intermittent clouds" |
4 |
"hazy sunshine" |
5 |
"lots of clouds" |
6 |
"cloudy skies" |
7 |
"dreary weather" |
8 |
"fog" |
11 |
"showers" |
12 |
"clouds and showers" |
13 |
"clouds with a chance of showers" |
14 |
"thunderstorms" |
15 |
"lots of clouds and thunderstorms" |
16 |
"some sun and thunderstorms" |
17 |
"rainy weather" |
18 |
"snow flurries" |
19 |
"an abundance of clouds and snow flurries" |
20 |
"some sun and snow flurries" |
21 |
"snowy weather" |
22 |
"lots of clouds and snow" |
23 |
"icy weather" |
24 |
"sleet" |
25 |
"cold weather and freezing rain" |
26 |
"snowy rainy weather" |
29 |
"high temperatures" |
30 |
"cold temperatures" |
31 |
"lots of wind" |
32 |
"clear skies" |
33 |
"mostly clear skies" |
34 |
"just a few clouds in the sky" |
35 |
"cloudy skies moving in and out" |
36 |
"haze" |
37 |
"clouds" |
38 |
"clouds and showers" |
39 |
"lots of clouds with showers" |
40 |
"some clouds with a chance of thunder showers" |
41 |
"clouds with thundershowers" |
42 |
"clouds with snow flurries" |
43 |
"lots of clouds with snow fall" |
44 |