In this tutorial, I want to show you how to send proactive events with your Alexa Skills built with Jovo. This will enable you to send notifications to your users both from inside your Alexa Skill as well as outside of a session.
- Alexa Skill Permissions and Publications
- Proactive Event Object
- Get the Access Token
- Send the Proactive Event
- Triggering the Proactive Event API from Outside
Docs: Alexa Proactive Events API.
The feature to send out notifications was one of the most requested ones in the early days of Alexa Skill development. In 2017 it was announced that the feature would be tested by a limited amount of handpicked developers. Although it was never released to the public fully, it got redesigned to the Proactive Events API, which was released in December of 2018.
The Proactive Events API's only use case, as of yet, is to send out notifications, but Amazon plans to expand the API in the future.
These notifications come with restrictions, the biggest one being that you have to implement one of Amazon's event schemas, which themselves come with certain restrictions to the values you're allowed to use.
Just like with the Proactive Events API itself, it seems to be planned to expand the available schemas, so you should keep an eye on the list, even if you don't find anything of use as of yet.
To use the Proactive Events API you have to follow these steps:
- Alexa Skill Permissions and Publications: Add the Proactive Events API and other necessary settings to your Alexa Skill.
- Proactive Event Object: Prepare the event object containing the data that will be sent.
- Get the Access Token: Request an access token from Amazon, which you get after authorizing to be able to send out the events.
- Send the Proactive Event
To be able to use the Proactive Events API, you have to add it to the permissions that your Alexa Skill needs to function. Besides that, you also have to specify the event schemas you're implementing, to which your users can subscribe to.
For that, you have to modify your
project.js file and add the following:
publications array should only include the event schemas you're actually implementing. For this tutorial, we only need the
For these changes to take effect, you have to build and deploy your project. In this case, we don't need to redeploy anything besides the
info files (
skill.json), which we can do the following way:
After the deployment finished, you can find the
clientSecret on the
PERMISSIONS tab of your Skill on the Alexa Developer Console, which you will need later on:
Note: Sometimes, it can take a bit for them to appear. If they don't show up right away, try to refresh your browser window.
The Proactive Event object contains the data you want to send to your users, as well as settings like the
expiryTime of the notification, which represents the date and time at which the notification will be deleted automatically.
We will create a new intent called
WeatherAlertIntent, where we will prepare and later on send out the Proactive Event.
You can find out more about the Proactive Event object and its attributes here
Now that we have Proactive Event object prepared, we have to request the access token, that's needed to send the Proactive Event. The access token will be granted after we've authorized ourselves with Amazon using the
clientSecret we got earlier:
With the Proactive Event object and the access token prepared, we can now send the Proactive Event:
WeatherAlertIntent looks like this:
That's all you need to send out an event using the Proactive Events API.
But, there is one issue. How are you going to trigger the intent to send out the event? You might find a creative solution where you somehow route through the
WeatherAlertIntent in the middle of a session, but even then you are bound to there actually being a session in the first place, which pretty much nullifies to actual benefits of the Proactive Events API, namely messaging your user while they're not using your Skill.
There are certain event schemas, where it will be perfectly fine to run the Proactive Events API inside your Alexa Skill. These are schemas that depend on two users, i.e. one user's action is the trigger to send out the notification to the other. For example, the
SocialGameInvite.Available scheme, where you will send out a notification to user 2 if user 1 invited them.
Other event schemas work a little different. Their trigger comes from an external source, e.g. the
SportsEvent.Updated event schemas. In the next section, we will go over a basic idea on how you might trigger the intent externally.
This section won't help you create the whole trigger but rather show you the part where you trigger your Jovo project, e.g. we won't go over the steps explaining how you might set up an AWS Lambda function, which gets executed as soon as there is a weather alert, but rather the part where we send out a request to our Jovo project to send out the Proactive Event, i.e. trigger the
To trigger the intent with the code to send out events, in our case the
WeatherAlertIntent, we have to send a request to our endpoint with the intent set to one executing the Proactive Event.
That intent should not be included in your language model to prevent your user may be randomly triggering it.
Here's a sample request, which you can use:
As you can see the
request object simply has the
intent set to
WeatherAlertIntent, besides that, everything is unimportant. The
applicationId, etc. don't matter.
To trigger the intent, you simply use this request as the body of a https request sent to your endpoint:
Simply call the function and parse the stringified request object as a parameter to trigger your Alexa Skill's
Depending on the region you are in, you have to change the
apiEndpoint property of the request:
- North America:
- Far East:
For testing purposes, we use the Jovo Webhook as it is the most convenient one for local testing. If you later on host your project on AWS Lambda, you might use an AWS API Gateway which you point to the Lambda function and send the request to the API endpoint. Technically it works the same for every other cloud service provider. You simply want to send the https request to the endpoint, where your project is hosted on.
If the notification didn't show up on your Echo device connected to the dev account, please check if the necessary permission was given for the skill to send notifications. You can find the option under
That's it, you made it to the end!