Intents
In this section, you will learn more about how to use intents to route your users through your voice app.
Introduction
Besides at least one of the the required LAUNCH or NEW_SESSION intents, you can add more intents that you defined at the respective developer platforms like this:
Whenever your application gets a request from one of the voice platforms, this will either be accompanied with an intent (which you need to add), or the signal to start or end the session.
For this, Jovo offers standard, built-in intents, LAUNCH and END, to make cross-platform intent handling easier:
Standard Intents
You can learn more about Jovo standard intents in the following sections:
LAUNCH
The LAUNCH intent is the first one your users will be directed to when they open your voice app without a specific question (no deep invocations, just "open skill" or "talk to app" on the respective platforms). If you don't have NEW_SESSION defined, this intent is necessary to run your voice app.
NEW_SESSION
You can use the NEW_SESSION intent instead of the LAUNCH intent if you want to always map new session requests to one intent. This means that any request, even deep invocations, will be mapped to the NEW_SESSION intent. Either LAUNCH or NEW_SESSION are required.
This is helpful if you have some work to do, like collect data (timestamps). After all data collection is done, Jovo automatically goes to the intent of the request.
If there are asynchronous calls that need to be executed before the original intent is entered, use the following:
There is no need to redirect to the next intent. For example, if you define the following handlers:
You receive the following log output for new sessions:
NEW_USER
Additionally to the other intents above, you can use the NEW_USER to direct a new user to this intent and do some initial work before proceeding to the interaction:
For example, this saves you some time calling if (this.$user.isNew()) { } in every intent where you require the access to user data.
If there are asynchronous calls that need to be executed before the original intent is entered, use the following:
There is no need to redirect to the next intent. For example, if you define the following handlers:
You receive the following log output for new users:
ON_REQUEST
The ON_REQUEST intent can be used to map every incoming request to a single intent first. This is the first entry point for any request and does not need to redirect to any other intent.
If you make any async calls in the ON_REQUEST intent, it is recommended to store data like this:
There is no need to redirect to the next intent. For example, if you define the following handlers:
You receive the following log output for new sessions:
END
A session could end due to various reasons. For example, a user could call "stop," there could be an error, or a timeout could occur after you asked a question and the user didn't respond. Jovo uses the standard intent END to match those reasons for you to "clean up" (for example, to get the reason why the session ended, or save something to the database).
getEndReason
It is helpful to find out why a session ended. Use getEndReason inside the 'END' intent to receive more information. This currently only works for Amazon Alexa.
Unhandled
Sometimes, an incoming intent might not be found either inside a state or among the global intents in the handlers variable. For this, Unhandled intents can be used to match those calls:
Tutorial: How the Unhandled Intent works.
Global Unhandled Intent
One Unhandled intent may be used outside a state to match all incoming requests that can't be found globally.
In the below example all intents that aren't found, are automatically calling the Unhandled intent, which redirects to LAUNCH:
State Unhandled Intents
Usually, when an intent is not found inside a state, the routing jumps outside the state and looks for the intent globally.
Sometimes though, you may want to stay inside that state, and try to capture only a few intents (for example, a yes-no-answer). For this, Unhandled intents can also be added to states.
See this example:
This helps you to make sure that certain steps are really taken in the user flow.
However, for some intents (for example, a CancelIntent), it might make sense to always route to a global intent instead of Unhandled. This can be done with intentsToSkipUnhandled.
intentsToSkipUnhandled
With intentsToSkipUnhandled, you can define intents that aren't matched to an Unhandled intent, if not found in a state. This way, you can make sure that they are always captured globally.
In the below example, if a person answers the first question with "Stop," it is not going to Unhandled, but to the global END:
ON_ERROR
Jovo uses the standard intent ON_ERROR to catch error requests:
With Alexa Skills, you can use the getError method:
Intent Hierarchy
Jovo intent handling works with promises. This means that the response is returned after the promise is resolved, even if no specific tell or ask is set. For certain Jovo standard intents it can happen that the handling passes through several intents without you having to use a redirect like toIntent.
The Jovo standard intents follow this hierarchy:
NEW_USERNEW_SESSIONON_REQUESTLAUNCH(or other intent that is called)
For example, this code:
Would return the following logs for a LAUNCH request from a new user:
After the request has passed through all the intents and no output is set, an empty response is returned.
Built-in Intents
As mentioned above, the platforms offer different types of built-in intents.
- Amazon Alexa: Standard built-in intents
- Google Assistant: Built-in Intents (Developer Preview)
intentMap
In cases where the names of certain intents differ across platforms, Jovo offers a simple mapping function for intents. You can add this to the configuration section of your voice app:
This is useful especially for platform-specific, built-in intents. One example could be Amazon's standard intent when users ask for help: AMAZON.HelpIntent. You could create a similar intent on Dialogflow called HelpIntent and then do the matching with the Jovo intentMap.
This can also be used if you have different naming conventions on both platforms and want to match both intents to a new name. In the below example, the AMAZON.HelpIntent and an intent called help-intent on Dialogflow are matched to a Jovo intent called HelpIntent.