Your Alexa Dashboards Settings

Display Interface Reference

Echo Show allows skill developers to create skills for Alexa that use both screen and voice interaction. The screen displays and interactions are created with the use of templates and the Display interface, as described in this reference. For general guidance on creating a skill, see Steps to Build a Custom Skill. To learn more about Echo Show, see Build Skills for Echo Show.

Configure Your Skill for the Display Directive

The process to enable the use of the Display.RenderTemplate directive, which is the directive used to display content on Echo Show, is the same for a new skill, or for an existing skill.

  1. On the Skill Information page for your skill, in the Amazon Developer Portal, select Yes for Render Template. Note that you can also select Yes for Audio Player and Video App support, if you want those to be part of your skill.
Global Fields Directives
Global Fields Directives
  1. On the Interaction Model page, you can choose whether to use Skill Builder, or the default page, for building your interaction model.
    • If you use the default Interaction Model page, in the Intent Schema, include the desired built-in intents for navigating your templates in your intent schema, as you would if creating a voice-only skill. Ensure you include the required built-in intents.
    • If you select Skill Builder, note the required built-in intents that are already included. You can include whatever other intents that your skill require. See Available Standard Built-In Intents for Echo Show.
  2. In the service code that you write to implement the skill, implement each of these specified built-in intents as desired. Include the Display.RenderTemplate directive in your skill responses to display content on screen as appropriate, just as you would include other directives, as shown in the examples below.

Types of Display Templates for Skills With Screen Capability

To include screen displays on Echo Show in their skill, a skill developer must use display templates. These templates are constructed so as to provide a great deal of flexibility for the skill developer. Each template has a JSON representation, and can be included as appropriate in the skill responses sent to Echo Show.

The Alexa Skills Kit provides two categories of display templates, each with several specifically defined templates for display on Echo Show:

  • A body template displays text and images. These images cannot be made selectable.
  • A list template displays a scrollable list of items, each with associated text and optional images. These images can be made selectable, as described in this reference.

These templates differ from each other in the size, number, and positioning of the text and images, as well as list-scrolling behavior, but each template has a prescribed structure. These templates have been carefully constructed to provide a consistent user experience for skills with Echo Show support.

When you, as the skill developer, construct a response that includes a display template, you specify the template, text, and images, so you have latitude to provide the user experience you want.

Template Interfaces (JSON) and Designs

For the JSON interface for each of these templates, the strings for the text or image fields may be empty or null. However, list templates must include at least one list item.

The skill icon you have selected for the skill in the Amazon Developer Portal appears in the upper right corner of every template automatically, and is rescaled from the icon images provided in the developer portal. You can change this skill icon in the portal as desired.

Each body template adheres to the following general interface:

  • Body Template Interface
{
  "type": "string",
  "token": "string"
}

Each list template adheres to the following general interface:

  • List Template Interface
{
  "type": "string",
  "token": "string",
  "listItems": [ ]
}

Form of the Display.RenderTemplate directive

The template attribute identifies the template to be used, as well as all of the corresponding data to be used when rendering it. Here is the form for a directives object that contains a Display.RenderTemplate directive. The type property has the value of the template name, such as BodyTemplate1 in this example. The other template properties will differ depending on the type value.

{
  "directives": [
    {
      "type": "Display.RenderTemplate",
      "template": {
        "type": "BodyTemplate1",
        "token": "string",
        "backButton": "VISIBLE",
        "backgroundImage": "Image",
        "title": "string",
        "textContent": {
          "primaryText": {
            "text": "string",
            "type": "string"
          },
          "secondaryText": {
            "text": "string",
            "type": "string"
          },
          "tertiaryText": {
            "text": "string",
            "type": "string"
          }
        }
      }
    }
  ]
}

See the formats for other templates in the Display Template Reference.

Display.RenderTemplate and Other Directives in Responses

For context, a response body that includes Display and Hint directive is shown below.

An AudioPlayer or a VideoApp directive cannot be combined with other directives.

{
  "version": "string",
  "sessionAttributes": {
    "string": "<object>"
  },
  "response": {
    "outputSpeech": {
      "type": "string",
      "text": "string",
      "ssml": "string"
    },
    "card": {
      "type": "string",
      "title": "string",
      "content": "string",
      "text": "string",
      "image": {
        "smallImageUrl": "string",
        "largeImageUrl": "string"
      }
    },
    "reprompt": {
      "outputSpeech": {
        "type": "string",
        "text": "string",
        "ssml": "string"
      }
    },
    "directives": [
      {
        "type": "Display.RenderTemplate",
        "template": {
          "type": "string"
        }
      },
      {
        "type": "Hint",
        "hint": {
          "type": "PlainText",
          "text": "string"
        }
      }
    ],
    "shouldEndSession": boolean
  }
}

Example: Directive for BodyTemplate2 to Include in a Response

The rendered body template shown in this example will display the title “My Favorite Car”, with a back button at the upper left, the skill icon at the upper right, and an image at the right, with the image scaled, if needed, to the appropriate size for this template. The back button and background image are optional, but are included here.

{
  "type": "Display.RenderTemplate",
  "template": {
    "type": "BodyTemplate2",
    "token": "A2079",
    "backButton": "VISIBLE",
    "backgroundImage": {
      "contentDescription": "Textured grey background",
      "sources": [
        {
          "url": "https://www.example.com/background-image1.png"
        }
      ],
      "title": "My Favorite Car",
      "image": {
        "contentDescription": "My favorite car",
        "sources": [
          {
            "url": "https://www.example.com/my-favorite-car.png"
          }
        ]
      },
      "textContent": {
        "primaryText": {
          "text": "See my favorite car",
          "type": "PlainText"
        },
        "secondaryText": {
          "text": "Custom-painted",
          "type": "PlainText"
        },
        "tertiaryText": {
          "text": "By me!",
          "type": "PlainText"
        }
      }
    }
  }
}

Display Template Reference

The body and list templates are designed to support a wide range of presentations.

The textContent field contains primaryText, secondaryText, and tertiaryText.

Each list template must include at least one list item.

A hint can be included on each template, by use of the Hint directive, except for BodyTemplate3 and ListTemplate1. See Hint Directive.

The back button appears by default on each template, but can be hidden. See: Back Button Object

See:

BodyTemplate1

Template Description JSON Format Use Cases
Full-width text
  • Title (optional)
  • Skill icon (provided in developer portal)
  • Rich or Plain text
  • Background image (optional)
{
  "type":"BodyTemplate1",
  "token": "string",
  "backButton": "VISIBLE"(default) | "HIDDEN",
  "backgroundImage": Image,
  "title": "string",
  "textContent": TextContent
}
  • Text-only
  • Scrollable
BodyTemplate1
BodyTemplate1

BodyTemplate2

Image right
  • Title (optional)
  • Skill icon (provided by developer portal)
  • Image (optional - can be a rectangle or square)
  • Rich or Plain text
  • Background image (optional)
{
  "type": "BodyTemplate2",
  "token": "string",
  "backButton": "VISIBLE"(default) | "HIDDEN",
  "backgroundImage": "Image",
  "title": "string",
  "image": Image,
  "textContent": TextContent
}
  • One image required
  • Not scrollable
  • Expandable text area
BodyTemplate2
BodyTemplate2

BodyTemplate3

Image left
  • Title (optional)
  • Skill icon
  • Image (optional - can be a rectangle or square)
  • Rich or Plain text
  • Background image (optional)
{
  "type": "BodyTemplate3",
  "token": "string",
  "backButton": "VISIBLE"(default) | "HIDDEN",
  "backgroundImage": "Image",
  "title": "string",
  "image": Image,
  "textContent": TextContent
}
  • Scrollable
  • Expandable text area
BodyTemplate3
BodyTemplate3

BodyTemplate6

Full-screen image with text overlay
  • No title
  • Skill icon
  • One full-screen image (1024 x 600 for background)
  • Rich or Plain text
{
  "type": "BodyTemplate6",
  "token": "string",
  "backButton": "VISIBLE"(default) | "HIDDEN",
  "backgroundImage": Image,
  "title": "string",
  "image": "Image",
  "textContent": TextContent
}
  • Can be used as a welcome screen to offer guidance.
  • Not scrollable.
BodyTemplate6
BodyTemplate6

BodyTemplate7

  • Header text
  • Skill icon
  • Full-width, scalable ImageView for foreground image
  • Background image (optional)
{
  "type": "BodyTemplate7",
  "token": "SampleTemplate_3476",
  "backButton": "VISIBLE",
  "title": "Sample BodyTemplate7",
  "backgroundImage": {
    "contentDescription": "Textured grey background",
    "sources": [
      {
        "url": "https://www.example.com/background-image1.png"
      }
    ]
  },
  "image": {
    "contentDescription": "Mount St. Helens landscape",
    "sources": [
      {
        "url": "https://example.com/resources/card-images/mount-saint-helen-small.png"
      }
    ]
  }
}
BodyTemplate7 is designed specifically to support scalable foreground images.
Echo Show Header Text
Echo Show Header Text

ListTemplate1

Vertical list
  • Title (optional)
  • Skill icon
  • Rich or Plain text
  • Ordinals
  • Background image (optional)
  • Thumbnail images (optional)
  • Primary, secondary (optional), and tertiary (optional) text
{
  "type": "ListTemplate1",
  "token": "string",
  "backButton": "VISIBLE"(default) | "HIDDEN",
  "backgroundImage": "Image",
  "title": "string",
  "listItems": [
    {
      "token": "string",
      "image": Image,
      "textContent": TextContent
    },
    ...
    ...
    {
      "token": "string",
      "image": Image,
      "textContent": TextContent
    }
  ]
}
  • Static or dynamically-generated search results, menu selection, lists, instructions, directions
  • Text and optional images
  • Scrollable by touch and voice
  • Non-expandable text area

This image shows a template with primaryText and tertiaryText, with secondaryText omitted.

ListTemplate1
ListTemplate1

ListTemplate2

Horizontal list with text under image
  • Title (optional)
  • Skill icon
  • Rich or Plain text
  • Ordinals
  • One or more images (optional)
  • Background image (optional)
{
  "type": "ListTemplate2",
  "token": "string",
  "backButton": "VISIBLE"(default) | "HIDDEN",
  "backgroundImage": "Image",
  "title": "string",
  "listItems": [
    {
      "token": "string",
      "image": Image,
      "textContent": TextContent
    },
    ...
    ...
    {
      "token": "string",
      "image": Image,
      "textContent": TextContent
    },
  ]
}
  • Static or dynamically-generated search results, menu selection, lists
  • Images required
  • Scrollable by touch and voice
  • Non-expandable text area
ListTemplate2
ListTemplate2

Display Template Elements

This table lists all of the elements that can be found in a display template, although each template might use only a subset of these elements.

Element Description Values/Examples
typeName of the templateBodyTemplate1
BodyTemplate2
BodyTemplate3
BodyTemplate6
ListTemplate1
ListTemplate2
tokenUsed to track selectable elements in the skill service code. The value can be any user-defined string.Dog-List-2
1212323312
backButtonUsed to place the back button on a display template.HIDDEN
VISIBLE
backgroundImageUsed to include a background image on a display template.
{
    "contentDescription": "string",
    "sources": [
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {...}
    ]
}
titleUsed for title for a display template. The value can be any user-defined string."Doggie Carousel"
"Cake Recipes Galore"
textContentContains primaryText, secondaryText, and tertiaryText.
{
    "primaryText": ...,
    "secondaryText": ...,
    "tertiaryText": ...
}
primaryText Contains type (which is PlainText or RichText) and text (which is a string).
{
    "text": "string",
    "type": "PlainText" | "RichText"
}
secondaryText Contains type (which is PlainText or RichText) and text (which is a string).
{
    "text": "string",
    "type": "PlainText" | "RichText"
}
tertiaryText Contains type (which is PlainText or RichText) and text (which is a string).
{
    "text": "string",
    "type": "PlainText" | "RichText"
}
image References and describes the image. Multiple sources for the image can be provided. The same format is used for both `backgroundImage` and `image`.
{
    "contentDescription": "string",
    "sources": [
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {...}
    ]
}
listItemsContains the text and images of the list items.
  [
    {
      "token": "string",
      "image": "Image",
      "textContent": "TextContent"
    },
    ...
    ...
    {
      "token": "string",
      "image": "Image",
      "textContent": "TextContent"
    }
  ]

GUI Specifications for Display Templates

Ensure you follow these specifications to ensure your skill works correctly and looks good on Echo Show.

Image Size and Format Allowed by Display Templates

The images that are referenced in display templates must meet the following requirements.

  • These images may be in either JPEG or PNG formats, with the appropriate file extensions.
  • An image cannot be larger than 2 MB. However, for speedier responses and to manage latency issues, a maximum of 500 KB is recommended for a background image, and 100 KB for other images referenced in a display template.
  • The templates provide support for either square or rectangular images. Note the aspect ratio for each template shown in the table.
  • When including the image, it is recommended that you provide several different URL sizes. The image size selected will be the smallest possible size that matches the desired aspect ratio and gives a clear image for the size of the screen where the image is being rendered. See the display sizes in the following table. If you do not provide an image of the appropriate size, the next larger image size will be scaled down for use to fit the intended slot. Because scaling down may cause poor image quality, it is strongly recommended that you provide appropriately sized images.
  • You must host the images at HTTPS URLs that are publicly accessible.
  • For the best visual experience, ensure images are transparent. (Only images in PNG format can be transparent.)
  • By the judicious use of a transparent background, your images can appear to take on a wide range of shapes and sizes.
  • Background images with slight patterns or gradients are recommended to provide a consistent, high-quality appearance.
  • If you want an overlay of text on top of a background image, you must include the overlay in the image itself. A 70% opacity black layer is recommended for optimal contrast.

The same restrictions that apply to images used on cards in the Alexa app also apply to images used in Echo Show templates. See Image Format and Size.

Display Image Sizes for Each Template for Echo Show

The following table lists image sizes supported by each template. With the backgroundImage field, the display size is the same as for the Echo Show screen: 1024px x 600px.

For the image referenced in the image field, the sizes are as follows for each template.

Template Display Size (pixels):
Maximum Height x Width
List Template 1 (vertical text)88 x 88
List Template 2 (horizontal with text under image) Height should be 280 pixels. Depending on the aspect ratio desired, the width should be between 192 and 498 pixels. The following aspect ratios are supported (width x height):
  • Portrait (192 x 280)
  • Square (280 x 280)
  • 4:3 (372 x 280)
  • 16:9 (498 x 280)
BodyTemplate1 (full-width text)inline images only
BodyTemplate2 (image right)340 x 340
BodyTemplate3 (image left)340 x 340
BodyTemplate6 (full-screen image with text overlay)340 x 340

Image Object Specifications

The image object in the display templates takes the following format. Note that the image format used for images on cards is different.

The contentDescription property is text used to describe the image for a screen reader. The fields size, widthPixels, and heightPixels are optional. By default, for Echo Show, size takes the value X_SMALL. If the other size values are included, then the order of precedence for displaying images begins with X_LARGE and proceeds downward, which means that larger images will be downscaled for display on Echo Show if provided. For the best user experience, include the appropriately sized image, and do not include larger images.

Do not include the widthPixels and heightPixels integer values, which are optional, unless they are exactly correct.

{
  "image": {
    "contentDescription": "string",
    "sources": [
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {
        "url": "string",
        "size": "string",
        "widthPixels": integer,
        "heightPixels": integer
      },
      {...}
    ]
  }
}

The values for size are listed in the following table.

Property Description Recommended Size (in pixels)
Width x Height
X_SMALL Displayed within extra small containers 480 x 320
SMALL Displayed within small containers 720 x 480
MEDIUM Displayed within medium containers 960 x 640
LARGE Displayed within large containers 1200 x 800
X_LARGE Displayed within extra large containers 1920 x 1280

Back Button in Echo Show Templates

For some skills with a visual component, a back button allows the customer greater freedom to navigate through the skill. In other such as quiz games, the inclusion of a back button might cause incorrect or undesired behavior, such as if the customer uses the back button to return to a previously answered question. The skill developer can decide whether to include a back button, which appears at the upper left, on each display template used in the skill. The backButton field can be used with each display template.

The backButton object can have the attribute “HIDDEN” or “VISIBLE”. If not included in a template response, then by default the back button will be shown on the screen.

If the customer states “go back”, that has the same effect as invoking the AMAZON.Previous intent in your skill.

These two examples show how the backButton object appears in a response that includes a display template.

Example: Will Not Include Back Button on Display Template

{
  "template": {
    "type": "BodyTemplate1",
    "textContent": {
      "primaryText": {
        "text": "See my favorite car",
        "type": "PlainText"
      },
      "secondaryText": {
        "text": "Custom-painted",
        "type": "PlainText"
      },
      "tertiaryText": {
        "text": "By me!",
        "type": "PlainText"
      }
    },
    "backButton": "HIDDEN"
  }
}

Example: Includes Back Button on Display Template

{
  "template": {
    "type": "BodyTemplate1",
    "textContent": {
      "primaryText": {
          "text": "See my favorite car",
          "type": "PlainText"
      },
      "secondaryText": {
          "text": "Custom-painted",
          "type": "PlainText"
      },
      "tertiaryText": {
          "text": "By me!",
          "type": "PlainText"
        }

    },
    "backButton": "VISIBLE"
  }
}

Include Hint Directives in Responses

When a customer looks at an Echo Show screen display, it may not be clear what to do next. The use of hints helps the customer know what to do. Hints follow a specified format.

The Hint directive allows a string value that informs the user what to ask Alexa. When displayed on screen, the hint text appears in the following set form:

*"Try <wake-word>, <hint_String>"*

Thus, if the value is "tell me what movies are playing", and the customer has their wake word set to "Alexa", the hint appears as follows:

*Try "Alexa, tell me what movies are playing"*

If you include hint directives as appropriate with responses that include display templates, the customer experience will be much improved. For brevity, the following example shows only the Hint directive, but a typical response with a hint would also include a Display.RenderTemplate directive.

{
  "directives": [
    {
      "type": "Hint",
      "hint": {
        "type": "PlainText",
        "text": "string"
      }
    }
  ]
}

textContent Object Specifications

The textContent object, found in all templates, allows for primaryText, secondaryText, and tertiaryText fields, which may be styled differently. With the ListTemplate1 template, the text is automatically styled to match these hierarchy levels. For the other templates, the text listed for each of primaryText, secondaryText, and tertiaryText is concatenated, with line breaks added between each, and no difference in font between the lines. Each of primaryText, secondaryText, and tertiaryText has the same format.

{
  "textContent": {
    "primaryText": TextField,
    "secondaryText": TextField,
    "tertiaryText": TextField
  }
}

In each case, TextField is represented as follows. If type is set to PlainText, no markup is included. If type is set to RichText, the markup described in Supported Markup can be included.

{
"type": "PlainText"  | "RichText",
"text": "string"
}

PlainText and RichText are the only supported type values.

If type is set to RichText, you can use the supported markup and supported XML characters to change the appearance of the text. See Supported Markup for Text in Display Templates.

In addition, if type is set to RichText, you can use an inline image, with an absolute file path, can be used for the value of “text”. The height of the image has no specific restriction. The maximum width is 880px, which accounts for left and right padding.

In the “text” field, you can include text that is wrapped in an action tag, which is then selectable on the screen.

In this example, the word “Cancel” is wrapped in an action tag that gives it the value ‘cancel_trip’. When the customer touches the word “Cancel” on the screen, this triggers a Display.ElementSelected event with a token value of ‘cancel_trip`. The skill developer can then use this token to map this touch interaction to trigger the appropriate behavior in the skill service code.

<action value='cancel_trip'>Cancel</action>

Example: Plain Text Instance

  {
    "type": "PlainText",
    "text": "Welcome to My Skill"
  }

Example: Rich Text Instance

{
    "type": "RichText",
    "text": "Welcome to <b>My Skill</b>"
}

Character Count Maximums for Display Templates

Echo Show allows limited text on the screen, depending on the template used, and the font size used. If the included text exceeds these limits, the text is truncated on the screen display. The user cannot scroll to see the remaining text. Ensure that the text you use in the templates does not exceed these limits.

Markup is not included in the maximum character limits. These character limits are based on a font size of 32px, and must be adjusted proportionately if another font size is used. The default font size is 32px.

For each template, the maximum for the title is 200 characters.

Template Main Text Field
List Template 1 (vertical text) 84 total
List Template 2 (horizontal with text under)) 84 total
Body Template 1 (full-width text) 85 total
Body Template 2 8000 total
Body Template 3 8000 total
Body Template 6 85 characters total

Font Size Mapping for Echo Show

If no font size is specified, the largest font size is used. For best control of your display, specify the font size. The default font size is 32px.

Font Size Pixels on Echo Show
Font size="2" 28px
Font size="3" 32px (default)
Font size="5" 48px
Font size="7" 68px

Supported Markup for Text in Display Templates

The following markup elements, as well as XML special characters and Unicode characters, are supported for rich text, but not plain text. The format is always UTF-8. For encoding certain special characters, see Handle XML Special Characters.

Name Element Example Markup Output
Line break <br/> First line<br/>Second line First line
Second line
Bold <b> This is a <b>ladybird</b> beetle This is a ladybird beetle
Italics <i> Scientific name <i>Coccie nellidae</i> Scientific name Coccienellidae
Underline <u> Always <u>feed</u> your ladybird tasty aphids. Always feed your ladybird tasty aphids.
Font Sizes <font size="2"> small (28px) </font>
<font size="3"> medium </font>
<font size="7"> large (68px) </font>

<font size="7">Cake</font> <br> <font size="3">This is the best cake recipe ever. <br>

<font size="2">- Flour</font> <br>

<font size="2">- Sugar</font> <br>

Cake
This is the best cake recipe ever.
- Flour
- Sugar
Action

<action token="VALUE">clickable text </action>

The clickable text can be tapped on the Echo Show screen.
Learn the <action token="2347"> history </action> of ladybirds. Learn the history of ladybirds.
Inline images

<img src='URL' width='WIDTH' height='HEIGHT' alt='TEXT' />

Image loaded from the Internet. Supports auto-sizing the image to fit line height, alignment to baseline or text bottom.
This is an inline <img src='https://www.example.com/test1.jpg' width='500' height='500' alt='test image' /> image.
Rich Text with Inline Image

Handle XML Special Characters

Templates and cards differ in how they display special characters. If you want to use the following characters in the content for a display template, escape them as follows:

  • ampersand (&) is escaped to &amp;
  • double quotes (“) are escaped to &quot; or \"
  • single quotes (‘) are escaped to &apos; or \'
  • less than (<) is escaped to &lt;
  • greater than (>) is escaped to &gt;
  • slash (\) is escaped to \\
  • non-breaking space is escaped in XML format as &#160; (do not use HTML format)

Example: Use BodyTemplate3 in a Response to Create a Screen Display

The template BodyTemplate3 is a simple body template consisting of fields that you can specify: text, title, token, and image. In this example, the optional backButton, and backgroundImage are not included. The skill icon always appears on the screen at the top right when a display template is rendered onscreen. The skill icon is specified separately when you create the skill on the Developer Portal.

To create this template, include a Display.RenderTemplate directive in your JSON response:

  • Set the type to BodyTemplate3
  • Set the title field and textContent object to indicate the text to display
  • Set the image object with URL properties and a contentDescription (for use by screen readers).
  • Set the backButton attribute if you want to toggle between hidden and visible back buttons. Otherwise, by default
{
  "type": "Display.RenderTemplate",
  "template": {
    "type": "BodyTemplate3",
    "title": "Body Template Title Example",
    "token": "SampleCard_92347",
    "textContent": {
      "primaryText": {
        "type": "RichText",
        "text": "Example of text content. This content contains <b>bold text</b>, <i>italics</i>, and <br/> line breaks."
      }
    },
    "image": {
      "contentDescription": "Mount St. Helens landscape",
      "sources": [
        {
          "url": "https://example.com/resources/card-images/mount-saint-helen-small.png"
        }
      ]
    },
    "backButton": "HIDDEN"
  }
}

Example: Use ListTemplate1 in a Response to Create a Screen Display

List templates contain a scrollable list of items, which can be presented vertically with text only or horizontally with accompanying images on Echo Show. With ListTemplate1, you get a vertical list of items. This ListTemplate1 template has a single title field (displayed at the top of the screen), a backgroundImage, and a listItems field. Each list item contains optional token, textContent, and image fields. To create this display:

  • Include a Display.RenderTemplate directive in your JSON response.
  • Set the template type to ListTemplate1.
  • Set the title string to the desired value.
  • Set the backgroundImage string to the desired URL.
  • Define each list item.
{
  "type": "Display.RenderTemplate",
  "template": {
    "type": "ListTemplate1",
    "token": "list_template_one",
    "title": "Pizzas",
    "listItems": [
      {
        "token": "item_1",
        "image": {
          "sources": [
            {
              "url": "http://www.example.com/images/thumb/SupremePizza1.jpg"
            }
          ],
          "contentDescription": "Supreme Large Pan Pizza"
        },
        "textContent": {
          "primaryText": {
            "type": "RichText",
            "text": "<font size='7'>Supreme</font> <br/> Large Pan Pizza $17.00"
          },
          "secondaryText": {
            "type": "PlainText",
            "text": "Secondary Text"
          },
          "tertiaryText": {
            "type": "PlainText",
            "text": ""
          }
        }
      },
      {
        "token": "item_2",
        "image": {
          "sources": [
            {
              "url": "http://www.example.com/images/thumb/MeatEaterPizza1.jpg"
            }
          ],
          "contentDescription": "Meat Eater Large Pan Pizza"
        },
        "textContent": {
          "primaryText": {
            "type": "RichText",
            "text": "<font size='7'>Meat Eater</font> <br/> Large Pan Pizza $19.00"
          },
          "secondaryText": {
            "text": "Secondary Text",
            "type": ""
          },
          "tertiaryText": {
            "text": "",
            "type": "PlainText"
          }
        }
      }
    ]
  }
}

Example: Use ListTemplate2 in a Response to Create a Screen Display

ListTemplate2 produces a horizontal list. This ListTemplate2 template has a single title field (displayed at the top of the screen) and a listItems field. Each element in the list field contains optional token, textContent, and image fields. To create this display:

  • Include a Display.RenderTemplate directive in your JSON response.
  • Set the template type to ListTemplate1.
  • Set the title string to the desired value.
  • Set backButton values if appropriate.
  • Include the syntax for each list item, as shown.

In this example, the token list_template_two has no effect on the display, but you as the skill developer can use the token for tracking purposes in the skill service code to make the item selectable.

{
  "type": "Display.RenderTemplate",
  "template": {
    "type": "ListTemplate2",
    "token": "list_template_two",
    "title": "Pizzas",
    "listItems": [
      {
        "token": "item_1",
        "image": {
          "sources": [
            {
              "url": "http://www.example.com/images/thumb/SupremePizza1.jpg"
            }
          ],
          "contentDescription": "Supreme Large Pan Pizza"
        },
        "textContent": {
          "primaryText": {
            "type": "RichText",
            "text": "<font size='7'>Supreme</font> <br/> Large Pan Pizza $17.00"
          },
          "secondaryText": {
            "text": "Secondary Text",
            "type": ""
          },
          "tertiaryText": {
            "text": "",
            "type": "PlainText"
          }
        }
      },
      {
        "token": "item_2",
        "image": {
          "sources": [
            {
              "url": "http://www.example.com/images/thumb/MeatLoversPizza1.jpg"
            }
          ],
          "contentDescription": "Meat Lovers Large Pan Pizza"
        },
        "textContent": {
          "primaryText": {
            "type": "RichText",
            "text": "<font size='7'>Meat Lovers</font> <br/> Large Pan Pizza $17.00"
          }
        }
      }
    ]
  }
}

Handle Selection Events by Voice and Touch

Each item in a list can be made selectable by touch. For each selectable element on the screen, the skill developer provides an associated token that they will receive in the callback response when the element is selected. See the list templates in the Display Template Reference. The developer may name the tokens using their preferred methodology.

The skill can set a token field on any selectable element, and this token is returned in a Display.ElementSelected request if that element is selected. An example of such an event is shown below.

 "request": {
    "type": "Display.ElementSelected",
    "requestId": "amzn1.echo-api.request.7zzzzzzzzz",
    "timestamp": "2017-06-06T20:05:04Z",
    "locale": "en-US",
    "token": "getTopicName-Cookie-Contest"
  }

There is no built-in intent for selecting actions or list items. However, you can create an intent for this purpose and include it in the intent schema. This intent should be activated when the skill receives a Display.ElementSelected event in a response.

Design this intent so that if a list template is used, items shown on screen can be selected by the user saying the item name, or by saying the number of the item. The skill developer determines in the service (AWS Lambda or web service) whether a user can select by name or by ordinal.

The skill developer must create an intent, which is forwarded to the skill, to enable customers to vocally select list items and actions. The skill service should define intents for “select”, “open”, and “show” as well as for “number one”, “number two”, “one”, “two”, and so forth.

Each list item is tracked by use of a token in order to facilitate the correct response when a list item is selected by touch.

As the user progresses through a skill, different body and list templates may be used in the course of delivering the skill content. For example, with a recipe skill, the user may navigate from a search screen to selecting a recipe to viewing the ingredients to preparing the recipe, each requiring a separate screen display. The developer must plan this flow carefully.

The current screen display with a specified template remains on screen for a skill if the session is not ended, and no new template has been sent. If a response with a card is sent, the screen display with a template will remain in place. Thus, a skill could progress through multiple turns with the same screen in place, unless the display is purposefully changed with a skill response that includes a different template.

Template and Card Precedence Order for Display on Screen

For Echo Show, the response is parsed for display options. If there are multiple display options, the order of precedence for display is as follows:

  1. Display.RenderTemplate directive. The last-rendered template remains on the screen until another template is sent, or until the skill exits. Thus, the same template will remain on screen for multiple turns unless another template is explicitly sent.

  2. Card. If no template has been sent to the screen, but a card has been sent, this card is displayed on the screen. Cards are rendered on Echo Show using `BodyTemplate1.

  3. The default template (BodyTemplate1) is automatically created and displayed if there is no template or card specified in the skill response, and none is currently displayed on screen.

Determining the Version of the Supported Display

To ensure compatibility, the version of the markup and templates that are supported by the current device are sent in the device request. The only version that is currently supported is “1”, but providing support for these attributes in your response helps ensure backwards compatibility.

{
  "display": {
    "templateVersion": "1",
    "markupVersion": "1"
  }
}	
AttributeDescription
markupVersionVersion of markup.
templateVersionThe version of templates supported by the requesting device.
tokenThe token for the content currently shown on the display.

Format of Different GUI Responses for Echo Show and Devices Without Screens

This simple response supports only a card and speech response, and is what a developer would provide if not specifically supporting screen display. Note that if viewed on Echo Show, this card will be rendered using Body Template 1, which is the default template used for card display on Echo Show.

{
  "version": "1.0",
  "sessionAttributes": {
    "supportedHoroscopePeriods": {
      "daily": true,
      "weekly": false,
      "monthly": false
    }
  },
  "response": {
    "card": {
      "type": "Simple",
      "title": "Horoscope",
      "content": "You are going to have a good day today."
    }
  },
  "reprompt": {
    "outputSpeech": {
      "type": "PlainText",
      "text": "Anything else?"
    }
  }
}

The following response supports the same card and speech response, but also supports screen display via the use of a display template. In this example, BodyTemplate1 is used as the display template. In this example, the text on screen includes a phrase with bolded emphasis.

{
  "version": "1.0",
  "sessionAttributes": {
    "supportedHoroscopePeriods": {
      "daily": true,
      "weekly": false,
      "monthly": false
    }
  },
  "response": {
    "card": null,
    "outputSpeech": {
      "type": "PlainText",
      "text": "You are going to have a good day today."
    },
    "reprompt": {
      "outputSpeech": {
        "type": "PlainText",
        "text": "Anything else?"
      }
    },
    "directives": [
      {
        "type": "Display.RenderTemplate",
        "template": {
          "type": "BodyTemplate1",
          "token": "horoscope",
          "title": "This is your horoscope",
          "image": {
            "contentDescription": "Aquarius",
            "sources": [
              {
                "url": "https://example.com/resources/card-images/aquarius-symbol.png"
              }
            ]
          },
          "textContent": {
            "primaryText": {
              "type": "RichText",
              "text": "You are going to have a <b>good day</b> today."
            }
          }
        }
      }
    ],
    "shouldEndSession": false
  }
}

Validation Rules for Responses

Responses for devices with Alexa, including Echo Show, should follow these validation rules.

  • At most one Display.RenderTemplate directive can be specified in a response.
  • Do not include both an AudioPlayer.Play directive with long-form audio and a VideoApp.Launch directive together in the same response.
  • All required fields must be provided.
  • No unknown properties may be specified.

If the response is invalid, an error card appears on Echo Show, and an error is sent to the skill.

Use of shouldEndSession Attribute and Session Timeouts

When shouldEndSession is not specified, or has a value of null, and a Display.RenderTemplate directive is active, the session is kept open, and Echo Show does not expect a voice response. If the user says the wake word and a command, this utterance is recognized in the context of the skill.

To specifically control shouldEndSession behavior, set this attribute to true to end the session, or to false to continue the session.

If shouldEndSession is set to false and there is no reprompt, the skill will exit the session if there is no activity for 30 seconds.

If there is a reprompt, then the timeout for reprompt is 8 seconds with the microphone open and a blue ring displayed, plus 8 seconds for the customer to respond. If Alexa does not hear a response, then a reprompt is rendered, and the customer is given another 8 seconds to respond. If there is still no response, and shouldEndSession is set to false, the session remains open until the display times out.

Light and Dark Modes on Echo Show

Echo Show has two display modes: Light and Dark. The default mode depends on the light available in the room, although the user can switch modes if desired, through the device settings.

In Light mode, the screen has a white background with gray text. In Dark mode, the screen has a dark background with white text.

The skill developer cannot directly change the mode within the skill, nor can the developer query to see what mode is being used. All templates with a white background (Lists 1-3, and Body Templates 1, 2, 3, and 6) use the darker color scheme when the device is in Dark mode.

Note that if a display template uses a background image, the text is always white. Thus, for consistency, you can use a background image for all display templates to achieve a consistent appearance.

The BodyTemplate6 template, if used with a background image, appears the same in both modes and no changes in display occur with a changed mode.

The images specified by the templates are not inverted or altered in any way depending on the mode, nor can you change the images used in each mode. Thus, the skill developer must test the skill in both modes to ensure the images are legible. For example, all-white or all-black images without a contrasting outline will not display correctly in the corresponding mode.

Best Practices for Skill Development with Echo Show

See Best Practices for Echo Show Skills.

Test Your Skill with a Visual Simulator

On the Test tab in the developer portal, you can use the Service Simulator to test what templates look like when rendered, even if you do not have an Echo Show device.

This simulator is subject to the following restrictions:

  • Only custom skills are currently supported
  • The display is a close representation of what you see on Echo Show, but not pixel-perfect
  • The skill is not functional in the simulator, and nothing in the simulator is clickable. Session is not maintained.
Service Simulator Includes Screen Support
Service Simulator Includes Screen Support

See: Testing a Custom Skill