Alexa.Presentation.HTML Interface

Implement the Alexa.Presentation.HTML interface in your Alexa skill to integrate with a web app to build voice-enabled games that can run on Alexa devices with a screen. For more details about the Alexa Web API for Games, see About Alexa Web API for Games.

Start directive

Your skill sends the Alexa.Presentation.HTML.Start directive to notify the Alexa Service that you want to start a web app at the specified HTTPS link. Send this message from your skill to launch your web app on an Alexa-enabled device.

Include the data property to send the initial startup information to your web app, if any. The fields defined in this JSON payload can be anything and should include all of the information you need for the web app to show the correct state to your player at the start of the visual experience.

Alexa.Presentation.HTML.Start directive example

Copied to clipboard.

{
    "type": "Alexa.Presentation.HTML.Start",
    "data": {
        "arbitraryDataKey1": "My arbitrary data"
    },
    "request": {
        "uri": "https://mydomain.example.com/mygame.html",
        "method": "GET",
        "headers": {
            "Authorization": "Basic eyJ "
        }
    },
    "configuration": {
        "timeoutInSeconds": 300
    }
}

Alexa.Presentation.HTML.Start payload details

Field Description Type Required
type Must be Alexa.Presentation.HTML.Start string Yes
data Optional startup data to send the web app when it launches.
You can provide any valid JSON object with your data. Maximum size is 24 KB.
JSON object No
request Request information for the web app being loaded. A request object Yes
configuration Information needed to initialize the HTML runtime. A configuration object Yes
transformers Array of speech transformations to apply to the data object.. A transformers object No

configuration object

The configuration object defines how long the web app can run with no user interaction.

configuration object details

Property Description Type
timeoutInSeconds The number of seconds your web app can run without user interaction. Default value is 30 seconds. Maximum allowed value is 300 seconds. string

request object

The request object defines how the Alexa Service should start your web app.

request object details

Property Description Type
uri URI of the web app to start. string
methods The HTTP method used to load the URI. Must be GET. string
headers (Optional) HTTP headers used by your web app to access resources.
For example, if your app requires authorization, provide the authToken here.		 map

transformers object

The transformers object defines how to convert speech into an audio stream and provides a URL to that stream to your web app.

Both the HandleMessage and Start directives can take an optional transformers array. If you use transformers in the directive, you can use the fetchAndDemuxMP3 method in your web app to parse the audio stream. For more details, see Use transformers to render voice natively in HTML.

transformers object details

Each transformer in the array has the following properties.

Property Description Type
inputPath Path to the content to transform. This path must reference a property within the data or message object in your directive. string
outputName (Optional) Name of the property to add to the message object with the output.
If no outputName is supplied, the transformer overrides the inputPath with the transformed output.		 string
transformer The type of the transformer.
Valid values: ssmlToSpeech and textToSpeech.		 string

HandleMessage directive

Your skill can send arbitrary data to the web app by using the Alexa.Presentation.HTML.HandleMessage directive. The web app can register a callback to receive the messages from your skill.

Alexa.Presentation.HTML.HandleMessage directive example

Copied to clipboard.

"directives": [
    {
      "type": "Alexa.Presentation.HTML.HandleMessage",
      "message": {
        "anyInfoYouWantKey": "anyInfoValue"
      },
      "transformers": [
        {
          "inputPath": "mySsml",
          "transformer": "ssmlToSpeech",
          "outputName": "myTransformedSsml"
        }
      ]
    }
  ]

Alexa.Presentation.HTML.HandleMessage payload details

Field Description Type Required
type Must be Alexa.Presentation.HTML.HandleMessage string Yes
message Any arbitrary data to send the web app.
You can provide any valid JSON object with your data. Maximum size is 24 KB. 		JSON object Yes
transformers Array of speech transformations to apply to the data object.. A transformers object No

Message event

Your skill receives the Alexa.Presentation.HTML.Message when the web app sends a message with alexa.skill.sendMessage().

Alexa.Presentation.HTML.Message event example

Copied to clipboard.

{
    "request": {
    "type": "Alexa.Presentation.HTML.Message",
    "message": {
      "anyOtherInfoYouWantKey": "anyOtherInfoValue"
    }
  }
}

Alexa.Presentation.HTML.Message payload details

Field Description Type Required
type Must be Alexa.Presentation.HTML.Message string Yes
message Any arbitrary data to send the web app.
You can provide any valid JSON object with your data. Maximum size is 24 KB. 		JSON object Yes
Was this page helpful?

Last updated: May 01, 2024