Feature

SDK for Amazon Alexa

Marketplace Product

This is an SDK with APIs you will find useful for developing and deploying a custom Amazon Alexa skill. Custom skills can be implemented with Java, JavaScript or Codeless. The APIs available in the SDK can be consumed from any of these programming languages. The SDK should be installed from Backendless Marketplace using Backendless Console. Once installed, the APIs become instantly available in your Backendless app.

About The Product

Developing a custom Amazon Alexa skill requires you to process information from the Amazon Alexa requests. For example, your skill may need to determine the intent or obtain a value for a slot. These and other utility APIs are available in the SDK for Amazon Alexa. Additionally, publishing your skill to Amazon’s Alexa skill store requires a special validation of the skill. The SDK includes an implementation of the validation algorithm which you can embed into your skill implementation.

Installation

To install the SDK:

Login to Backendless Console and select your app
Click the Marketplace icon in the vertical toolbar on the left.
Click the All Services section and locate the SDK for Amazon Alexa.
Click the Install button and then click Activate in the popup.
Once installed, you will be able to confirm it by going to the Business Logic section of the console. You will see the AlexaUtils API service which provides the APIs documented below:

Available APIs

The SDK provides access to the following APIs:

getIntentName – retrieves the name of the intent from the request sent by the Alexa service.
getSlotValue – retrieves the value for a slot for an intent.
sendAlexaResponse – sends a response back to the Alexa service.
sendProgressiveAlexaResponse – sends an intermediary “progressive” response to Alexa while the skill is processing the original request. The progressive response is useful when you want to let the user know that the skill is still processing the request and needs more time. For more information about progressive Alexa responses, see the documentation.
verifyRequest – performs a verification of the request sent by the Alexa service. This is a required operation for the custom skills published to the Amazon Alexa skills store.
getRequestType – returns the type of the Alexa service request received by the skill. Returns one of the following values: LaunchRequest, IntentRequest or SessionEndedRequest.
isStarted, isInProgress, isCompleted – provide information about the state of the slots for the current intent. As the user answers Alexa/skill’s questions and provides more information to fill up the slots, the APIs help the developer to determine if all the slots have the information.

getIntentName

The getIntentName API has one argument, which is the request object sent by the Alexa service. The API returns a String value which is the name of the intent. The API can be invoked from a custom Alexa skill as shown below:

From Java code:

Object[] args = new Object[] { request }; 
String intentName = Backendless.CustomService.invoke( "AlexaUtils", "getIntentName", args, String.class );

From JavaScript code:

Backendless.CustomServices.invoke( "AlexaUtils", "getIntentName", request )
  .then( function( intentName ) {
    // use the intentName value
  });

From Codeless logic:

getSlotValue

The API has three arguments: (1) request object sent by the Alexa service, (2) intent name and (3) slot name. The operation locates the specified intent in the request and then retrieves the value for the specified slot name.

Using the API from Java code:

String intentName = "weather";
String slotName = "city";
Object[] args = new Object[] { request, intentName, slotName };
String slotValue = Backendless.CustomService.invoke( "AlexaUtils", "getSlotValue", args, String.class );

Using the API from JavaScript code:

var intentName = "weather"; 
var slotName = "city"; 

var args= {
  request:request,
  intentName:intentName,
  slotName:slotName 
};

Backendless.CustomServices.invoke( "AlexaUtils", "getSlotValue", args ) 
.then( function( intentName ) {
  // use the intentName value 
});

Using the API from a Codeless logic:

sendAlexaResponse

The API delivers a response from the skill to the Alexa service. The operation accepts two arguments: (1) a String object with a response which will be spoken to the user by Alexa. The string may contain SSML tags and (2) a boolean value indicating whether Alexa should wait for a response from the user.

Using the API from Java code:

boolean waitForResponse = false;
Object[] args = new Object[] { request, waitForResponse };
Backendless.CustomService.invoke( "AlexaUtils", "sendAlexaResponse", args, Object.class );

Using the API from JavaScript code:

var waitForResponse = false;

var args= {
  request:request,
  waitForResponse:waitForResponse
};

Backendless.CustomServices.invoke( "AlexaUtils", "sendAlexaResponse", args );

Using the API from a Codeless logic:

sendProgressiveAlexaResponse

A progressive response can be used whenever your skill needs more time to process a request and you want to let the user know you are still working on it. A progress response doesn’t require any response from the user, it is more of a verbal update so the user knows what’s going on. Think about it as a spoken “progress bar” indicating the progress of the performed action. For more information about progressive responses, see Amazon’s documentation. The operation accepts two arguments: (1) current request from Alexa, this is the request which the skill is processing and (2) a String object with a response which will be spoken to the user by Alexa. The string may be either plain text or contain SSML tags.

Using the API from Java code:

String progressiveResponse = "Please wait while I process your request";
Object[] args = new Object[] { request, progressiveResponse };
Backendless.CustomService.invoke( "AlexaUtils", "sendProgressiveAlexaResponse", args, Object.class );

Using the API from JavaScript code:

var progressiveResponse = "Please wait while I process your request";
var args= { request:request, speech:progressiveResponse };
Backendless.CustomServices.invoke( "AlexaUtils", "sendProgressiveAlexaResponse", args );

Using the API from a Codeless logic:

verifyRequest

Alexa service request verification is a mandatory step for any custom Alexa skill which will be published to the Amazon Alexa Skills store. Verification is a part of the certification requirements. This API performs request verification so your skill can take advantage of it with a single API call. The API accepts a single argument which is the request object. If the request is valid, the skill’s code will continue the execution. Otherwise, an error will be thrown and code execution will be aborted.

Using the API from Java code:

Map<String, String> httpHeaders = InvocationContent.getHttpHeaders();
String signatureCertChainUrl = httpHeaders.get( "signatureCertChainUrl" );
String signature = httpHeaders.get( "signature" );
Object[] args = new Object[] { signatureCertChainUrl, signature, request };
Backendless.CustomService.invoke( "AlexaUtils", "verifyRequest", args, Object.class );

Using the API from JavaScript code:

var waitForResponse = false;

var args= {
  request: request, // request object declared as the skill method argument
  Signature: this.request.headers.Signature,
  SignatureCertChainUrl: this.request.headers.SignatureCertChainUrl
};

Backendless.CustomServices.invoke( "AlexaUtils", "verifyRequest", args );

Using the API from a Codeless logic:

getRequestType

Determines and returns the type of the request from the Alexa service. The return value can be one of the following:

LaunchRequest – a request sent by the Alexa service when the user invokes the skill with the invocation name, but does not provide any data to map the request to an intent.
IntentRequest – sent when the user speaks a command which maps to an intent. The request includes the specific intent and defined slots (not all the slots may be filled yet, see the isCompleted method for more information).
SessionEndedRequest – a request when a currently open session is closed. The session can be closed when (1) the user says “exit”, (2) the user does not respond or says something that does not match an intent in your voice interface, (3) an error occurs.

For more information on request types, see Amazon’s documentation.

Using the API from Java code:

Object[] args = new Object[] { request };
Backendless.CustomService.invoke( "AlexaUtils", "getRequestType", args, Object.class )
  .then( function( result ) {
    console.log( "request type is " + result );
  });

Using the API from JavaScript code:

var args= {
  request: request // request object declared as the skill method argument
};

String requestType = (String) Backendless.CustomServices.invoke( "AlexaUtils", "getRequestType", args );

Using the API from a Codeless logic:

isStarted, isInProgress, isCompleted

These APIs let you quickly determine the state of the slots for the intent. As the user provides information which fills up the slots the state of the request transforms from “started” to “completed”. The APIs help you determine the state of the request with regards to how completed the slots are with the data provided by the user:

isStarted – returns true if none of the slots have been filled up with the data provided by the user;
isInProgress – returns true if some of the slots have been filled up with the data provided by the user;
isCompleted – returns true if all of the slots have been filled up with the data provided by the user;

Using the API from Java code:

Object[] args = new Object[] { request };
Backendless.CustomService.invoke( "AlexaUtils", "isInProgress", args, Object.class )
  .then( function( result ) {
    console.log( "request processing is in progress " + result );
  });

Using the API from JavaScript code:

var args= {
  request: request // request object declared as the skill method argument
};

Boolean requestType = (Boolean) Backendless.CustomServices.invoke( "AlexaUtils", "isInProgress", args );

Using the API from a Codeless logic: