Alexa.Presentation.HTML Interface Reference

The Alexa.Presentation.HTML interface provides directives and requests for integrating your skill with a web application. You can use this interface along with the Alexa JavaScript API to build voice-enabled games that can run on Alexa devices.

For more details about the Alexa Web API for Games, see Understand the Alexa Web API for Games.

Configure your skill to support HTML directives

To enable the HTML directives in your skill, you must add the ALEXA_PRESENTATION_HTML interface in your skill manifest. For details about the skill manifest, see Skill Manifest Schema.

To add support for the ALEXA_PRESENTATION_HTML interface

  1. Open the developer console, locate the skill you want to configure, and then click Edit.
  2. Navigate to the Build > Interfaces page.
  3. Enable the Alexa Web API for Games interface.
  4. Click Save Interfaces, and then, to re-build your interaction model, click Build Model.

If you use ASK CLI or SMAPI to build your skill, you can edit the skill manifest directly to add the ALEXA_PRESENTATION_HTML interface to your interfaces object. You can then use ASK CLI or SMAPI to deploy the changed manifest.

If your skill also uses Alexa Presentation Language (APL), be sure to include both Alexa.Presentation.HTML and ALEXA_PRESENTATION_APL. The following example shows the interfaces array for a skill that supports both the APL and HTML interfaces.

Copied to clipboard.

    "apis": {
      "custom": {
        "interfaces": [
          {
            "type": "ALEXA_PRESENTATION_HTML"
          },
          {
            "type": "ALEXA_PRESENTATION_APL",
            "minimumTemplateVersion": "1.0"
          }		  
        ]
      }
    }

After you save your manifest file, use the Alexa Skills Kit Command Line Interface to deploy the changed manifest.

For more details about updating your skill for supported interfaces, see the following topics:

Verify that the device supports HTML

Before your skill code sends any Alexa.Presentation.HTML directives, make sure the user's device supports the HTML interface. Check the context.System.device.supportedInterfaces object in the LaunchRequest for [Alexa.Presentation.HTML]. Support for the HTML interface is separate from support for APL. A device might support APL, but not support HTML. Therefore, check for the HTML support separately. The following example shows the context.System.device.supportedInterfaces object with both HTML and APL support.

Copied to clipboard.

    "device": {
      "deviceId": "amzn1.ask.device.XXXX",
      "supportedInterfaces": {
        "Alexa.Presentation.HTML": {
          "runtime": {
            "maxVersion": "1.0"
          }
      },
        "Alexa.Presentation.APL": {
          "runtime": {
            "maxVersion": "1.4"
          }
        }
      }
    }

Objects

configuration

The configuration object defines 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

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

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

Directives

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

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
    }
}

HandleMessage directive

Your skill can send arbitrary data to the web app by using the Alexa.Presentation.HTML.Start directive. The web app can register a callback to listen for the messages.

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

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

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

Alexa.Presentation.HTML.Message event example

Copied to clipboard.

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

Restrictions of the HTML environment

The following browser capabilities are disabled when you include support for the ALEXA_PRESENTATION_HTML interface in your skill:

  • Geolocation in the browser
  • getUserMedia (camera, mic)
  • alert(), prompt(), confirm() with JavaScript
  • SpeechRecognition with the Web Speech API
  • Loading a URL from a file, file://</path>
  • Local file API
  • Content URL access
  • Web SQL database
  • Local storage
  • Non-HTTP assets/URI. HTTPS is required.

The following browser capabilities are available to use with Alexa.Presentation.HTML.Start. These capabilities are cleared after every Start directive.

  • Cookies
  • History
  • Form data

The sendMessage rate is limited to 2 TPS.