Your Alexa Consoles
?
Support

Display Interface and Template Reference

To create a skill that supports screen display on Echo Show and Echo Spot, see Create Skills for Echo Devices With a Screen.

This reference describes how to use display templates in the skill service code to achieve the look and feel that you want for your skill. Remember that many users will be using Echo devices without screen support, so your skill should always be designed in a voice-first manner.

See also:

 

Types of Display Templates for Skills That Support Screen Display

To include screen displays in their skill, a skill developer must use display templates in the skill service code. 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 the screen.

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

  • 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.

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 and a VideoApp directive cannot be combined together.

{
  "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

On Echo Show, 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 templates 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.

For Echo Show, the back button appears by default on each template, but can be hidden. The back button does not appear on Echo Spot, but the customer can achieve the same effect with a long swipe from the left. See: Back Button Object

See:

BodyTemplate1 for Simple Text and Image Views

Echo ShowEcho Spot
  • Header text left-aligned
  • Skill icon
  • Full-width TextView, top and left aligned, default font size 7, scrollable (if needed)
  • Allowance for small, in-line images
  • Background image (optional)
  • Header text center-aligned
  • Skill icon
  • TextView top and left aligned, default font size 7, scrollable (if needed)
  • Allowance for small, in-line images
  • Background image (optional)

Guidelines:

  • This template does not support full-width foreground images. Instead, developers should use BodyTemplate7 for this purpose.
  • Line lengths with the default font size of 7 will vary, so text will wrap differently on Echo Spot versus Echo Show.
  • If scrolling is needed, the full screen, including the skill icon, header text, and body content will scroll via touch.

BodyTemplate1 Syntax

{
  "type":"BodyTemplate1",
  "token": "string",
  "backButton": "VISIBLE"(default) | "HIDDEN",
  "backgroundImage": Image,
  "title": "string",
  "textContent": TextContent
}

Device Display Comparison–BodyTemplate1

BodyTemplate1 with short text
BodyTemplate1 with short text
BodyTemplate1 with long scrolling text
BodyTemplate1 with long scrolling text
Echo ShowEcho Spot
Echo Show Header Text
Echo Show Header Text
Echo Show Header Text
Echo Spot Header Text
Echo Show Header Text
Echo Show Scrolling Text
Echo Show Header Text
Echo Spot Scrolling Text

BodyTemplate2 for Image Views and Limited Centered Text

Display Characteristics

Echo ShowEcho Spot
  • Header text
  • Skill icon
  • TextView left, aligned left, default font size 3, no scrolling
  • Foreground image right
  • Hint (optional)
  • Action links (optional)
  • Background image (optional)
  • No header text
  • Skill icon
  • TextView left, aligned center, default font size 3, scrollable (if needed), text will layer on top
  • Foreground image will become the background image, with a 70% opacity black scrim over it
  • Action links (optional)
  • Background image (optional), and will not show unless there is no foreground image or if the foreground image has a transparent background

Guidelines for using BodyTemplate2:

  • Use BodyTemplate2 when you have a limited amount of text that is paired with an image.
  • Keep the content short and concise, to supplement but not to replace the VUI.
  • Content that displays as side-by-side on Echo Show is stacked on Echo Spot. The image in the background, and the text will layer on top of it.
  • Hints are not display on Echo Spot.
  • BodyTemplate2 and BodyTemplate3 render the same on Echo Spot, except that text is auto-centered on BodyTemplate2.
  • If scrolling is required, the full screen, including the skill icon, header text, and body content, will scroll via touch.
  • Do not include important information such as trademarks in the background image.

BodyTemplate2 Syntax

{
  "type": "BodyTemplate2",
  "token": "string",
  "backButton": "VISIBLE"(default) | "HIDDEN",
  "backgroundImage": "Image",
  "title": "string",
  "image": Image,
  "textContent": TextContent
}

Device Display Comparison–BodyTemplate2

BodyTemplate2
BodyTemplate2
Echo ShowEcho Spot
Echo Show Header Text
Echo Show Header Text
Echo Spot With No Header Text
Echo Spot With No Header Text
Echo Show Header Text
Echo Show Header Text
Echo Spot With No Header Text
Echo Spot With No Header Text

BodyTemplate3 for Image Views and Limited Left-Aligned Text

Display Characteristics

Echo ShowEcho Spot
  • Header text
  • Skill icon
  • TextView is on the right and left-aligned, scrollable (if needed), default font size 3
  • Foreground image left
  • Action links (optional)
  • Background image (optional)
  • No header text
  • Skill icon
  • TextView is on the left and left-aligned, default font size 3, scrollable (if needed), text will layer on top
  • Foreground image will become the background image, with a 70% opacity black scrim over it
  • Action links (optional)
  • Background image (optional)

Guidelines for using BodyTemplate3:

  • Content that is displayed side-by-side on Echo Show is stacked on Echo Spot. The image is in the background, and the text is layered on top of it.
  • Hints are not displayed on Echo Spot.
  • BodyTemplate2 and BodyTemplate3 are rendered the same on Echo Spot. Text is aligned left on BodyTemplate3.
  • If scrolling is required, the full screen, including the skill icon, header text, and body content, will scroll via touch.
  • Do not include important information such as trademarks in the background image.

BodyTemplate3 Syntax

{
  "type": "BodyTemplate3",
  "token": "string",
  "backButton": "VISIBLE"(default) | "HIDDEN",
  "backgroundImage": "Image",
  "title": "string",
  "image": Image,
  "textContent": TextContent
}

Device Display Comparison–BodyTemplate3

BodyTemplate3
BodyTemplate3
Echo ShowEcho Spot
Echo Show Header Text
Echo Show Header Text
Echo Spot With No Header Text
Echo Spot With No Header Text
Echo Show Header Text
Echo Show Header Text
Echo Spot With No Header Text
Echo Spot With No Header Text

BodyTemplate6 for Text and Optional Background Image

Display Characteristics

Echo ShowEcho Spot
  • Skill icon
  • Full-width TextView (2-3 lines max), bottom-aligned, left-aligned, default font size 7, no scrolling
  • Hint (optional)
  • Background image (optional)
  • Skill icon
  • TextView is middle- and center-aligned, scrollable (if needed), default font size 7
  • No hints appear on Echo Spot
  • Background image (optional)

Guidelines for BodyTemplate6:

  • Hints are not displayed on Echo Spot.
  • On Echo Spot, background images are scaled down based on the aspect ratio, and then centered within the available viewport. For example, a 1024x600px background image on Echo Show will be scaled to 819x480px on Echo Spot. Thus, part of a background image may not be visible on Echo Spot.
  • If scrolling is required on Echo Spot, the full screen, including the skill icon, header text, and body content, are scrolled via touch.

BodyTemplate6 Syntax

{
  "type": "BodyTemplate6",
  "token": "string",
  "backButton": "VISIBLE"(default) | "HIDDEN",
  "backgroundImage": Image,
  "image": "Image",
  "textContent": TextContent
}

Device Display Comparison–BodyTemplate6

BodyTemplate6
BodyTemplate6
Echo ShowEcho Spot
Echo Show Body Text
Echo Show Body Text
Echo Spot Body Text Without Hint
Echo Spot Body Text Without Hint

BodyTemplate7 for Scalable Foreground Image With Optional Background Image

Display Characteristics

Echo ShowEcho Spot
  • Header text
  • Skill icon
  • Full-width, scalable ImageView for foreground image
  • Background image (optional)
  • Header text
  • Skill icon
  • Full-width, scalable ImageView for foreground image
  • Background image (optional)

Guidelines for using BodyTemplate7:

  • BodyTemplate7 supports scalable foreground images on Echo Show and Echo Spot.
  • On Echo Spot, the foreground image will center within the viewable area, and will scale up and down appropriately, keeping the original aspect ratio.

BodyTemplate7 Syntax

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

Device Display Comparison–BodyTemplate7

BodyTemplate7 with a full-width foreground image
BodyTemplate7 with a full-width foreground image
BodyTemplate7 with a full-width foreground image
BodyTemplate7 with a full-width foreground transparent image
Echo ShowEcho Spot
Echo Show Header Text
Echo Show Header Text
Echo Show Header Text
Echo Spot Header Text

ListTemplate1 for Text Lists and Optional Images

Display characteristics

Echo ShowEcho Spot
  • Header text
  • Skill icon
  • List items:
    • Primary text, default font size 7
    • Secondary text (optional), default font size 3
    • Tertiary text (optional), default font size 5
    • Image (optional)
    • Background image (optional)
  • Header text
  • Skill icon
  • List items:
    • Primary text, default font size 7
    • Secondary text (optional), default font size 3
    • Tertiary text (optional), default font size 3
    • Image (optional),
    • Background image (optional)

Guidelines for using ListTemplate1:

  • Use this template for lists where images are not primary content
  • List items should be selectable via touch, and voice using the primary text or the ordinal
  • If using thumbnail images, the space for text is reduced
  • If there is more text than can be displayed on the screen, an ellipsis will appear

ListTemplate1 Syntax

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

Device Display Comparison–ListTemplate1

ListTemplate1 with primary and secondary text on the Echo Show and Echo Spot
ListTemplate1 with primary and secondary text on the Echo Show and Echo Spot
ListTemplate1 with primary, secondary, and tertiary text, and an optional list item image
ListTemplate1 with primary, secondary, and tertiary text, and an optional list item image
Echo ShowEcho Spot
Echo Show List
Echo Show List
Echo Show List
Echo Spot List
Echo Show List
Echo Show List
Echo Show List
Echo Spot List

ListTemplate2 for List Images and Optional Text

Display characteristics

Echo ShowEcho Spot
  • Header text
  • Skill icon
  • List items:
    • Primary text, default font size 2
    • Secondary text (optional), default size 24sp (undefined font size)
    • Image (square, portrait, 4:3 or 16:9)
    • Background image (optional)
    • Hint
  • Skill icon
  • List items:
    • Primary text, default font size 7
    • Secondary text (optional), default font size 2
    • List item image will become the background image, with a 70% opacity black scrim over it
    • Background image (optional)

Guidelines for using ListTemplate2:

  • Use this template for lists where images are the primary content.
  • List items should be selectable via both touch and voice using the primary text or the ordinal.
  • Do not nest action links within list item content. Action links will not be selectable by touch and may not be visible on Echo Spot.
  • Keep in mind that text will truncate on Echo Spot particularly, so make sure the primary text on the screen is descriptive enough that the customer is aware of what they are selecting.
  • Only one list item will be visible on the screen at a time.
  • Text will layer on top of the foreground image now, and be bottom-aligned.
  • Hints will not display on Echo Spot.
  • If there is more text than can be displayed on the screen, an ellipsis will appear.

ListTemplate2 Syntax

{
  "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
    },
  ]
}

Device Display Comparison–ListTemplate2

ListTemplate2 with a square image
ListTemplate2 with a square image
ListTemplate2 with a portrait image
ListTemplate2 with a portrait image
Echo ShowEcho Spot
Echo Show List
Echo Show List
Echo Show List
Echo Spot List

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
BodyTemplate7
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). Limit of 8000 characters.
{
    "text": "string",
    "type": "PlainText" | "RichText"
}
secondaryText Contains type (which is PlainText or RichText) and text (which is a string). Limit of 8000 characters.
{
    "text": "string",
    "type": "PlainText" | "RichText"
}
tertiaryText Contains type (which is PlainText or RichText) and text (which is a string). Limit of 8000 characters.
{
    "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 should 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. Images are compressed when sent, and decompressed when received.
  • 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.
  • For background images, a 70% opacity black layer should be applied for optimal contrast between the image and text.

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 for Echo Show. With the backgroundImage field, the display size is the same as for the Echo Show screen: 1024px x 600px. For Echo Spot, these images will be scaled down appropriately. Do not use smaller images which need to be scaled up, as they will have a poor appearance on a larger device.

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

Template Display Size (pixels):
Maximum Height x Width
ListTemplate1 (vertical text)88 x 88
ListTemplate2 (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

Echo Show supports back buttons on all templates, although the developer can choose to hide the back button. On Echo Spot, the back button does not appear at all, but the customer can achieve the same effect with a long swipe from the left edge of the screen, if the backButton object is set to "VISIBLE" as described in this section.

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

Hints should be used for optional content and to delight customers, and not for important information. If the Hint directive is used in a response, the hint is visible on Echo Show, but not visible on Echo Spot. Thus, every skill that uses hints should be designed so that the hints are optional.

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"*

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, and each is subject to an 8000-character limit.

{
  "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
ListTemplate1 (vertical text) 84 total
ListTemplate2 (horizontal with text under)) 84 total
BodyTemplate1 (full-width text) 85 total
BodyTemplate2 8000 total
BodyTemplate3 8000 total
BodyTemplate6 85 characters total
BodyTemplate7 No main text field for BodyTemplate7

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)

Text Alignment With Rich Text

Refer to textContent Object Specifications for general information on how to implement rich text.

Wherever the textContent object is used in a template, center alignment can now be done as follows, if type is set to RichText.

{
    "type" : "RichText",
    "text" : "<div align='center'>This text will align center</div>"
}

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": "PlainText"
          },
          "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": "PlainText"
          },
          "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 devices with screens, 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 Devices With and Without Screens

The simple response shown below 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 an Echo device with a screen, this card will be rendered using BodyTemplate1.

{
  "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 devices with screens, 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.

Best Practices for Skill Development with Echo Show

See Best Practices for Designing Skills for Echo Devices With a Screen.

Test Your Skill with a Visual Simulator

On the Test page in the developer console, you can use the Alexa 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:

  • No simulator is available for Echo Spot
  • 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.
Echo Show Simulator on the Test Page
Echo Show Simulator on the Test Page

See: Test Your Skill

Service Interface Reference (JSON)

Request Format and Standard Request Types:

Interfaces: