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.
Alexa.Presentation.HTML
interface.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
{
"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
"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
{
"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 |
Related topics
Last updated: May 01, 2024