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 |