Web API for Games Reference

When the user interacts with your web app, you can send messages between the app and the skill back end. The Web API for Games reference defines the objects and interfaces that your web app can use to communicate with your skill.

Alexa objects

Client

The Alexa Client object provides interfaces to communicate with your skill and with the device. See the Alexa HTML API for more details.

Client object details

Property Description Type
capabilities The device capabilities. A Capability object
performance Provides the interface to get the available memory on the device.
For more details, see performance		 A Performance object.
skill Provides the interfaces to communicate with your skill.
For more details, see onMessage and sendMessage.		 A Skill object.
speech Provides the interfaces to receive Alexa speech events.
For more details, see Alexa Speech Input.		 A Speech object.
version Version of the Alexa client.
If you don't specify a version, the latest version is used. 		string
voice Provides the interfaces to open the microphone on the device to receive user utterances.
For more details, see Alexa Voice.		 A Voice object.

Capability

The Capability object provides information about the device.

Capability object details

Property Description Type
microphone Capabilities of the microphone on the device. A Microphoneobject

Microphone

The Microphone object provides information about the device.

Microphone object details

Property Description Type
supportsPushToTalk Specifies whether the microphone activates when a user presses a physical button on the device or when a user uses a remote. boolean
supportsWakeWord Specifies whether the microphone activates when the user says a wake word.
When set to true, the web app can use the Voice interface to start microphone events.		 boolean

AlexaReadyPayload

The promise resolve result from a successful create invocation.

AlexaReadyPayload details

Property Description Type
alexa The initialized and ready Alexa client. An Alexa client object
message Start up information provided by the skill.
The JSON value from the data property of the Start directive.		 any

SendResponse

The callback receives the response to the sendMessage interface in a SendResponse object. For more details, see sendMessage.

SendResponse details

Property Description Type
statusCode The HTTP status code that indicates the status of the received message from the skill.
Valid values: 200 (OK), 401 (Unauthorized), 429(Too Many Requests), 500 (Internal Server Error/Unknown Error)		 integer
reason A text string that describes the error value found in the statusCode property. string
rateLimit The limit on the number of outgoing requests from your web app. A RateLimit object

RateLimit

The RateLimit object defines the limit on the number of outgoing requests from your web app.

RateLimit details

Property Description Type
maxRequestsPerSecond The maximum allowed requests per second. integer
remainingRequests The number of requests that might be delivered before the rate limiter blocks messages.
0 indicates no more messages are allowed.		 integer
timeUntilNextRequestMs The number of milliseconds until your app can send the next message. integer
timeUntilResetMs The number of milliseconds until remainingRequests equals maxRequestsPerSecond. integer

Alexa interfaces

capabilities

Check the device capabilities using the capabilities interface.

The following example shows a check for PushToTalk capability using a Microphoneobject.

Copied to clipboard.

    if (alexaClient.capabilities.microphone.supportsPushToTalk) {
        // Prompt the user to press the microphone button
        ...
    };

create

Establish the connection to Alexa on the device using the create interface as shown. create invokes the success function and returns a promise fulfilled by AlexaReadyPayload or rejects the promise and invokes the failure function.

Copied to clipboard.

let client;
Alexa.create({version?: "1.1", messageProvider?: new Alexa.DefaultMessageProvider()})
.then(success)
.catch(failure);

create interface details

Property Description Type
version (Optional) Version of the Alexa client.
Requesting an invalid version is rejected with no-such-version error code.		 string
messageProvider (Optional) Used for simulation or testing. A MessageProvider object
AlexaReadyPayload Fulfilled with an AlexaReadyPayload object. promise
success Invoked when create() is successful. The success method
failure Invoked when create() fails. The failure method

The createmethod invokes the success function when it successfully creates the Alexa client in AlexaReadPayload as shown. The message contains data sent from the skill.

Copied to clipboard.

const success = function(result) {
    const {alexa, message} = result;
    // Actions after Alexa client initialization is complete
};

The createmethod invokes the failure function when it fails to create the Alexa client as shown.

Copied to clipboard.

const failure = function(error) {
    const {
        code,
        message
    } = error;
    // Actions for failure to initialize
};

failure interface details

Property Description Type
code Error code that shows the reason to fail to create the Alexa client.
Valid values: no-such-version, unauthorized-access, too-many-requests, unknown 		string
message A text string that describes the error value found in the code property. string

performance

Use the performance interface to get the available memory on the device. This interface is useful in development for optimizing assets and debugging across device types.

The following example shows logging the available memory.

Copied to clipboard.

alexaClient.performance.getMemoryInfo().then((memInfo) => {
    // log memInfo
});

onMessage

Use the alexaClient.skill.onMessage to register a listener to handle messages sent from your skill. The messages sent to your listener are independent of the messages your app sends to your skill. The format of the message sent from the skill is agreed on between the app and the skill. The app can only register one callback, so the callback function should include logic to handle different messages based on the data provided within the message. Messages can't be received until you register the listener. If you need information from the skill on start-up, use the message returned in the successful create interface.

The following example shows registering a listener function called messageReceivedCallback.

Copied to clipboard.

// Register a listener to receive a message from your skill
alexaClient.skill.onMessage(messageReceivedCallback);

// Implement the listener
const messageReceivedCallback = function(message) {
    // Process message (JavaScript object) from your skill
};

onMessage interface details

Property Description Type
messageReceivedCallback The callback function used to process the received message. function
message Any arbitrary data formatted by your skill.
The JSON value from the data property of the HandleMessage directive.		 any

sendMessage

To send a message to your skill from your web app, use alexaClient.skill.sendMessage interface. The interface takes a data payload and an optional callback for handling the response. The API results in an Alexa.Presentation.HTML.Message to your skill.

The following example shows sending a message to the skill.

Copied to clipboard.

// Send a message to your skill
alexaClient.skill.sendMessage(message, messageSentCallback);

// Check the results of the SendMessage
const messageSentCallback = function(sendResponse) {
    const {
        statusCode,
        reason,
        rateLimit,
    } = sendResponse;
    // Handle response codes
};

sendMessage interface details

Property Description Type
message Any arbitrary data formatted by your app.
The JSON value sent in the data property of the Message directive.		 any
messageSentCallback The callback function used to process the results of the sendMessage. function
Was this page helpful?

Last updated: May 01, 2024