Amazon Alexa

Integration published by Jovo | 42,160 downloads

Build apps for Amazon's Alexa assistant platform

Requests

Introduction

The request is the incoming data that the Alexa platform sends to your app's endpoint. It consists of information like:

  • User ID,
  • Intent, e.g. MyNameIsIntent
  • Input, e.g. name
  • Session data, e.g. a state

and other things that might be relevant to your app. You can access the incoming request with this.$request.

Here's an example request:

You can find a detailed explanation of each of the request's properties here

Basic Request Types

Generally, we distinguish between three base request types, the LaunchRequest, IntentRequest, and the SessionEndedRequest. While there are a couple more request types, they are not enabled by default but rather depend on you adding one of the many interfaces, Alexa provides, to your Skill, e.g. Audio Player or Game Engine interface.

LaunchRequest

A LaunchRequest is sent to your endpoint whenever the user starts your Skill without triggering a specific intent, e.g. Alexa, start my test app:

You can find a detailed explanation of each of the request's properties here

IntentRequest

A IntentRequest is sent whenever the user triggers one of the intents defined in your language model. Besides the general request information like the id, timestamp, and the locale, it also provides data about the triggered intent and its slots:

You can find a detailed explanation of each of the request's properties here

SessionEndedRequest

A SessionEndedRequest is sent when the current session ends. That happens either when

  • the user manually ends it using "Alexa, exit",
  • the user doesn't respond or says something that does not match any of your intents
  • an error occurs

You can find a detailed explanation of each of the request's properties here

CanFulfillIntentRequest

The name-free interaction allows Amazon to map user requests, which don't specify a skill and can't be handled by Alexa's built in features, to be mapped to a developer's skill that can handle it.

For example, the user might make the following request: Alexa, play relaxing sounds with crickets. Alexa's built-in features can't handle the request so the system looks for third party skills to fulfill it.

The system will then send CanFullIntentRequests the skills it believes might be able to fulfill the request. According to the response to that requests (yes, no or maybe) your skill will receive an IntentRequest just as if it the skill was invoked my the customer directly.

CanFulfillIntentRequest Requirements

To enable the CanFulfillIntentRequest feature you have to enable the interface in your skill's information. You can do that either in the Alexa Developer Console in the Interfaces subcategory or you do it with the Jovo CLI.

Open your project.js file and add the following to your alexaSkill object:

Don't forget to build and deploy your project after you've added the interface:

CanFulfillIntentRequest Implementation

Incoming CanFulfillIntentRequests will be mapped to the Jovo built in CAN_FULFILL_INTENT.

After receiving an CanFulfillIntentRequest you have to answer the following question: Can my skill understand and fulfill every slot as well as understand and fulfill the whole request?.

Since every Skill is different, there is no universal recipe to use. You have to come up with our own way to handle these requests, which suits your skill, but there is a rough guideline:

Intent

The first step should be to check if the incoming intent is one, that your skill can handle. You can get the incoming intent name using this.getIntentName()

Slots

You also have to go over every slot in the request and decide if you can understand (YES, NO or MAYBE) and fulfill (YES or NO) the slot.

Use this.$inputs to get an object containing every slot. Iterate over the object and decide for each slot if you can understand it or not using:

Request

After going through the slots, you have to decide if you can also handle the whole request (YES, NO or MAYBE):

It is recommended to go over the official Amazon documentation (here and here) to get a better grasp about when to respond with YES, NO or MAYBE as well as other guidelines.

$request Object

Besides the cross-platform getter and setter methods the Alexa $request object supports the following general getter methods:

Getters

Name Description Return Value
getApiAccessToken() Returns the API access token used for Alexa specific APIs string
getApiEndpoint() Returns the API endpoint string
getAudioPlayerToken() Returns the Audio Player token which you have set using the Play directive. Is only present if you played audio right before the request. string or undefined
getDeviceId() Returns the unique identifier for the device string
getPersonId() Returns the unique identifier of the person who sent the request string
getRequestId() Returns the current request's id string
getScreenResolution() Returns the current devices screen resolution as "WidthxHeight". Undefined if the device has no screen. string or undefined
getSupportedInterfaces() Returns an object with each of its keys representing a supported interface object
hasAutomotive() Returns true if the Automotive object exists in the request's context boolean

Amazon Alexa Changelog

Jovo Marketplace | GitHub | npm

Current version might be higher than the latest changes displayed below because of updates of dependencies.

2020-08-21 [3.0.30]

3.0.17 (2020-05-13)

🐛 Bug fix

  • jovo-platform-alexa Fix http status in ReminderAPI

Committers: 1

3.0.13 (2020-05-04)

💅 Enhancements

  • jovo-platform-alexa #734 Add getPermissionIsCardThrown (@rmtuckerphx)
  • jovo-platform-alexa Add types for skill event body objects

Committers: 2

3.0.11 (2020-04-06)

  • Updated Typescript to 3.8.x
  • Updated Prettier to 2.x

Committers: 2

2.x

Find the 2.x changelog here.

Join Our Newsletter

Be the first to get our free tutorials, courses, and other resources for voice app developers.