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 along with the Alexa JavaScript API to build voice-enabled games that can run on Alexa devices.

Note that the Alexa Skills Kit SDKs do not provide support for the directives and requests in the Alexa.Presentation.HTML interface.

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

Configure your skill to support the ALEXA_PRESENTATION_HTML interface

The ALEXA_PRESENTATION_HTML interface must be defined in the skill manifest for skills to use HTML directives.

To add support for the ALEXA_PRESENTATION_HTML interface

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

If you are using 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.

Support for the Alexa.Presentation.HTML interface is separate from support for Alexa Presentation Language (APL). If your skill also uses APL, be sure to include both Alexa.Presentation.HTML and ALEXA_PRESENTATION_APL. For example, this example shows the interfaces array for a skill that supports both the APL and HTML interfaces.

See the following topics for more about updating your skill for supported interfaces:

Verify that the device supports Alexa.Presentation.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]. Note that 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. In this example, both the HTML and APL interfaces are supported.

Start Directive

Starts the web app at the specified uri. The headers.Authorization field is optional. If you use transformers in this directive, you can use the fetchAndDemuxMP3 function to fetch and demux an audio stream so as to extract the audio buffer and speech marks, as described in Use transformers to render voice natively in HTML.

Example of Alexa.Presentation.HTML.Start directive

"type":"Alexa.Presentation.HTML.Start",
"data": {
   "mySsml": "<speak>Hello</speak>"
},
"request": {
    "uri": "https://mydomain.example.com/mygame.html",
    "method": "GET",
    "headers": {
        "Authorization" : "Basic eyJ "
    }
},
"transformers": [
   {
     "inputPath": "mySsml",
     "transformer": "ssmlToSpeech",
     "outputName": "myTransformedSsml"
   }
],
"configuration": {
   "timeoutInSeconds": 300
}
Name Description Type Required

configuration.timeoutInSeconds

The number of seconds the content can stay on the screen without user interaction. Default value is 30 seconds. Maximum allowed value is 5 minutes.

Integer

Yes

configuration

Information needed to initialize the HTML runtime.

Object

Yes

data

Optional startup data for the web app when it launches. You can provide any valid JSON object with your data. Use the Alexa JavaScript API to access this data within your web app. Maximum size: 24 KB.

Object

No

request.headers

HTTP headers used by the web app to access resources. For example, if your app requires authorization, provide the authToken here.

Map

No

request.methods

HTTP method to load the URI with, such as GET.

String

Yes

request.uri

URI of the web app to start.

String

Yes

request

Request information for the web app being loaded.

Object

Yes

transformers.inputPath

Path to the content to transform. This path must reference a property within the data object.

String

Yes

transformers.outputName

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

No

transformers.transformer

An APL transformer, such as ssmlToSpeech. See Transformers.

String

Yes

transformers

Array of speech transformations to apply to the data object.

Object

No

type

Always Alexa.Presentation.HTML.Start.

String

Yes

HandleMessage Directive

A directive that handles a message to the web app. The web app can call FUNCTION to register a callback to listen for the messages.

If you use transformers in this directive, you can use the Speech.demux function to fetch and demux the audio stream, as described in Use transformers to render voice natively in HTML.

Example of HandleMessage Directive


"directives": [
    {
      "type":"Alexa.Presentation.HTML.HandleMessage",
      "message": {},
      "transformers" []

    }
  ]
Name Description Type Required

message

A free-form object containing the data to deliver to the device. Maximum size: 24 KB.

Object

Yes

transformers.inputPath

Path to the content to transform. This path must reference a property within the message object.

String

Yes

transformers.outputName

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

Yes

transformers.transformer

Type of the transformer. Possible values: "ssmlToSpeech", "textToSpeech". See Transformers.

String

Yes

transformers

Array of speech transformations to apply to the data object.

Object

No

type

Always Alexa.Presentation.HTML.HandleMessage.

String

Yes

Message Request

The request type your skill receives when the web app sends a message with alexa.skill.sendMessage().

{
    "request": {
    "type": "Alexa.Presentation.HTML.Message",
    "message": {}
  }
}
Name Description Type Required

message

A free-form object containing data to deliver to the skill. Maximum size: 24 KB.

Object

Yes

type

Always Alexa.Presentation.HTML.Message.

String

Yes

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 file:// urls
  • Local file API
  • Content URL access
  • Web SQL database
  • Local storage
  • Non-HTTP assets/uri (https is required)

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

  • Cookies
  • History
  • Form data

The sendMessage rate is limited to 2 TPS.

Transformer object

Both the HandleMessage and Start directives can take an optional transformers array. A transformer converts either SSML or plain text into an audio stream and provides a URL to that stream to your web app. The directives support the same ssmlToSpeech and textToSpeech transformers supported in Alexa Presentation Language.

For more information on implementing transformers, see Transformers.

Each transformer in the array has the following properties.

Name Description Type Required

inputPath

Path to the content to transform. This path must reference a property within the data object (when used with the Start directive) or message object (when used with the HandleMessage directive).

String

Yes

outputName

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

No

transformer

The type of the transformer. Possible values: "ssmlToSpeech", "textToSpeech".

String

Yes