TemplateRuntime 1.2

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

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

Version changes

• New templates for navigation
  • CHANGED RenderTemplate directive
    • ADDED LocalSearchDetailTemplate1 template
    • ADDED LocalSearchListTemplate2 template
    • ADDED TrafficDetailsTemplate template

Data flow

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

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

Rendering visual metadata

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

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

Capability assertion

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

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

Sample Object

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

Directives

RenderTemplate

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

The following templates are currently supported:

BodyTemplate1

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

Sample Message

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

Header Parameters

Payload Parameters

BodyTemplate2

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

Sample Message

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

Header Parameters

Payload Parameters

ListTemplate1

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

ToDo List

Calendar

Sample Message

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

Header Parameters

Payload Parameters

LocalSearchDetailTemplate1

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

Sample Message

{
  "directive": {
    "header": {
      "namespace": "TemplateRuntime",
      "name": "RenderTemplate",
      "messageId": "{{STRING}}",
      "dialogRequestId": "{{STRING}}"
    },
    "payload": {
      "token": "{{STRING}}",
      "type": "LocalSearchDetailTemplate1",
      "title": {
        "mainTitle": "{{STRING}}",
        "subTitle": "{{STRING}}"
      },
      "address": {{STRING}},
      "phoneNumber": {{STRING}},
      "provider": {{STRING}},
      "image": {{IMAGE_STRUCTURE}},
      "travelDistance": "{{STRING}}",
      "travelTime": "{{STRING}}",
      "offRouteTime": "{{STRING}}",
      "priceRange": "{{STRING}}",
      "url": "{{STRING}}",
      "rating": {
        "value": "{{STRING}}",
        "reviewCount": "{{STRING}}",
        "image": "{{IMAGE_STRUCTURE}}",
        "provider": "{{STRING}}" {
          "name": "{{STRING}}",
          "image": "{{IMAGE_STRUCTURE}}"
        },
      "coordinate": {
        "latitudeInDegrees": "{{DOUBLE}}",
        "longitudeInDegrees": "{{DOUBLE}}"
      },
      "currentStatus": {{STRING}},
      "travelDirection": {{STRING}},
      "hoursOfOperation": {
        "dayOfWeek": "{{STRING}}",
        "type": "{{STRING}}",
        "hours": {{STRING}}
      }
    }
  }
}

Header Parameters

Payload Parameters

LocalSearchListTemplate2

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

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

Sample Message

{
  "directive": {
    "header": {
      "namespace": "TemplateRuntime",
      "name": "RenderTemplate",
      "messageId": "{{STRING}}",
      "dialogRequestId": "{{STRING}}"
    },
    "payload": {
      "token": "{{STRING}}",
      "type": "LocalSearchListTemplate2",
      "onInteraction": "{{STRING}}",
      "title": {{STRING}},
      "sortType": {{ENUM}},
      "pointOfInterests" {
        "title" {
          "mainTitle": "{{STRING}}",
          "subTitle": "{{STRING}}"
        },
        "address": {{STRING}},
        "phoneNumber": {{STRING}},
        "provider": {{STRING}},
        "image": {{IMAGE_STRUCTURE}},
        "travelDistance": "{{STRING}}",
        "travelTime": "{{STRING}}",
        "offRouteTime": "{{STRING}}",
        "priceRange": "{{STRING}}",
        "url": "{{STRING}}",
        "rating": {
          "value": "{{STRING}}",
          "reviewCount": "{{STRING}}",
          "image": "{{IMAGE_STRUCTURE}}",
          "provider": "{{STRING}}" {
            "name": "{{STRING}}",
            "image": "{{IMAGE_STRUCTURE}}"
          },
        },
        "coordinate": {
          "latitudeInDegrees": "{{DOUBLE}}",
          "longitudeInDegrees": "{{DOUBLE}}"
        },
        "currentStatus": {{STRING}},
        "travelDirection": {{STRING}},
        "hoursOfOperation": {
          "dayOfWeek": "{{STRING}}",
          "type": "{{STRING}}",
          "hours": {{STRING}}
        },
      },
    },
  },
}

Header Parameters

Payload Parameters

TrafficDetailsTemplate

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

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

Sample Message

{
  "directive": {
    "header": {
      "namespace": "TemplateRuntime",
      "name": "RenderTemplate",
      "messageId": "{{STRING}}",
      "dialogRequestId": "{{STRING}}"
    },
    "payload": {
      "token": "{{STRING}}",
      "type": "TrafficDetailsTemplate",
      "title": {
        "mainTitle": "{{STRING}}",
        "subTitle": "{{STRING}}"
      },
      "skillIcon": {{IMAGE_STRUCTURE}},
      "destinationInfo": {
        "label": "{{STRING}}",
        "address": "{{STRING}}"
      },
      "travelDistance": "{{STRING}}",
      "travelTime": "{{STRING}}",
      "currentTrafficConditionsImage": {{IMAGE_STRUCTURE}},
      "backgroundImage": {{IMAGE_STRUCTURE}}
    }
  }
}

Header Parameters

Payload Parameters

WeatherTemplate

WeatherTemplate is a semantic template for rendering the weather forecast.

Sample Message

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

Header Parameters

Payload Parameters

RenderPlayerInfo

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

This example illustrates playback from Amazon Music:

Sample Message

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

Header Parameters

Payload Parameters

Control to Event Mapping

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

Image Structure

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

Image Size Specifications

Provides each supported enumeration of size.