Alexa Blogs
We recently released the ProactiveEvents API, which allows your Alexa skills to send notifications to customers who have granted permission. In today’s blog post, I’ll walk you through how to configure the ProactiveEvents API to solve a hypothetical business problem, and point to a sample project in the Alexa skill-building cookbook on GitHub for detailed instructions.
Before continuing, be sure to read the announcement blog post for an overview, and bookmark the ProactiveEvents API documentation page for reference.
The Hypothetical Scenario
Imagine a major curling sports league that has a schedule of games throughout the year that are broadcast on various channels. Fans may miss seeing games since they do not know the schedule or forget the channel to watch. The league has all the events recorded in a text file called schedule.txt, with details on the event name, event date, and network. They want to keep their customers aware of the upcoming schedule.
schedule.txt
| 2018-12-20T13:00:00.000Z, "Owls at Badgers", "Speech Radio" 2019-01-25T13:00:00.000Z, "Otters at Swans", "Listen Channel" 2019-02-14T13:00:00.000Z, "Pandas at Tigers", "Voice TV" 2019-03-17T13:00:00.000Z, "Snails at Otters", "Stream Site" … |
The league wants to provide the information via multiple ways to help their customers informed and engaged. First, customers can launch the skill to hear details about the next event, or they can enable notifications to receive automatic alerts about upcoming events one day in advance. The league has hired you to build a solution to solve both scenarios. You accept the challenge and roll up your sleeves to design and build a new voice-driven experience.
First, you verify your laptop command line has the AWS Command-Line Interface (CLI), the Alexa Skills Kit (ASK) CLI and Node.JS 8.
The Hypothetical Alexa Skill
How can you build such a skill for the league? You decide to write a function that opens the schedule file to find the next future event, and return the details in the skill speech output and later as part of a notification job.
You create a new skill project on your laptop, using the ASK CLI’s ask new command. Within the new project folder you open the manifest file, called skill.json.
To set up your skill customers to receive notifications, you update this file with two sections: permissions and events.publications, as shown:
| "permissions": [ {"name": "alexa::devices:all:notifications:write"} ] |
| "events"{ "publications":[ {"eventName": "AMAZON.MediaContent.Available"} ] } |
The permissions section allows you to define only the Proactive Events schema type(s) you want to use. Your skill suggests the customer enable notifications, and sends a Permission Request Card to the user’s Alexa app to make it easy to find the permissions settings. (When you send 
a multicast message out, Alexa routes it to only the customers who have enabled notifications.)
You are sure to complete the Build, Test, and Distribution sections of you skill to set the icons, which is necessary to start receiving Echo screen device banners.
Schemas
You browse and review all possible publication types available in the Proactive Events schemas, such as weather alerts, sports score updates, and appointment reminders.
The schema AMAZON.MediaContent.Available you choose is a good match for the league’s requirements. You can send out a notification that a certain broadcast is streaming the following day and on which provider.
{
"name": "AMAZON.MediaContent.Available",
"payload": {
"availability": {
"startTime" : "2019-01-25T13:00:00.000Z",
"provider": {
"name": "Listen Channel"
},
"method": "STREAM"
},
"content": {
"name": "Otters at Swans",
"contentType": "GAME"
}
}
}
Each customers who listens to the notification will hear a message like “<Otters at Swans> will stream on <January 25 2019 8 PM> on <Listen Channel>”. Customers with an Echo Show or Echo Spot will also see a notification banner on their home screen. 
You may opt to setup an AWS DynamoDB table along with your skill. This would enable you to track the userId of each customer, as well as any other persistent attributes. The userId values would be needed for sending individual, personalized notifications to customers.
The Script
You decide to generate notifications “out of session,” meaning separate from your skill’s normal AWS Lambda function. You write a Node.JS script that scans the schedule.txt file and locates the next future event, like the skill itself does. Your script then submits the event details as a new Proactive Event. The script will use skill-specific credentials that you copy from the Alexa Developer Console to generate a token, and then call the API.
After testing your script, you schedule a job to run it once per day, and show the customer how to maintain the schedule file.
Results
The league is delighted with your solution; after one month they are seeing a large bump in viewership for their games. They now have an Alexa skill that has a high retention and usage rate by providing experience that customers find valuable and worth returning to. The staff appreciates the integration between the skill and the custom schedule file they manage. And customers appreciate the ability to opt in and receive timely notifications from the skill. Well done!
Now that you've read through this post, think about how you can put these techniques and features to use in your own skills. Check out this step-by-step code sample from the feature demos section of the Alexa skill-building cookbook on GitHub. Be sure to run the sample in us-east-1 region.
Let's continue the discussion online! You can find me on Twitter @RobMcCauley.
