Adding Reminders to your Custom Alexa Skill

Amazon recently announced a new feature for Alexa skill developers, the Reminders API. This API allows you to set custom reminders for users of your skill which will play with a chime at the requested time and can also fire an alert on your mobile phone if you have the Alexa companion application installed, as shown below. Used properly, this new API has the promise to provide a lot of repeat engagement with your customers. In this post, I’ll talk about how I integrated reminders with two of my skills in ways that I believe provide true customer value and have the potential to increase engagement with my skills.

Reminders shown in the Alexa app

Use Case: Tournament Reminders

Some of my skills have a special “tournament round” which occurs every week. For Blackjack Game, every Tuesday you can play with a separate bankroll against other players to see who can get the highest bankroll within 100 rounds. For Slot Machine, there is a one hour window on Wednesday evening and Monday morning during which you try to get the highest bankroll with a rotating “tournament machine.” (I added a second weekly tournament on Monday mornings when this skill went live in Europe to better accommodate those customers.) For both of these skills, usage during the tournament windows spikes each week, proving it’s a popular product feature.

I’m especially happy with the Slot Machine tournament and I actually play it myself every now and then (I promise I don’t cheat!), and as a customer I’d find that sometimes I would forget about the tournament until it was over. When the Reminders API was announced, I knew that I had to incorporate it into my skill so users (including me!) could know when the tournament round was starting.

As with any new feature, I started with the conversational flow — how did I want to present this feature to customers, ensuring that they had an ability to set a reminder and understood the benefit of doing so, while not nagging them too often about it. I decided to provide this functionality in two ways — one with a new custom ReminderIntent that allowed them to specifically ask for a reminder (“set a weekly reminder for the tournament”) and the other by doing an upsell when the session was closing if a tournament was upcoming in the near future (“the next tournament starts in 10 hours. Would you like to set a weekly reminder for the tournament every Wednesday at 6 PM?”). In the latter case, I didn’t want to annoy the customer by asking this every time they played my skill, but I did want to prompt them occasionally since it was also in my benefit if they played the tournament. I also didn’t want to prompt them if they already had a reminder set for the upcoming tournament, and of course wanted to make sure they knew when that tournament was in their own timezone.

Implementation Details

With this flow in mind, there are three main steps that had to happen: (1) setting the reminder, (2) handling the response from the API, and (3) checking for an existing reminder before kicking off this flow. Let’s start with the code that sets the reminder.

For the moment, there isn’t a clean API within the ask-sdk to make the call to the Reminder API, however it’s simple enough to use a library like request-promise to issue the POST command directly to the endpoint provided in the Alexa request.

In my code, you can see that I’m setting the timezone to America/US_LosAngeles (Pacific time) in building the alert. That’s because the tournament round runs simultaneously world-wide for users — everyone is playing together! Setting the alarm in the right timezone should automatically adjust the reminder for customers who live in areas with no or different daylight savings rules than the West Coast tournament clock. You’ll also see that I’m using the moment package to get the two-character code needed to set byDay for a weekly reminder (being sure to first set the locale to English). I use this module elsewhere — if I weren’t I’d probably just use getDay() and hardcore an array of two-character day names instead.

In managing the response from this API, you have to keep in mind that it’s possible that attempting to set the reminder could fail. This will happen if the user doesn’t provide permission for the skill (in which case the error code will be UNAUTHORIZED), or if could be another error. In my case, I lump the set of other errors into a single “something went wrong” message, however I do provide the customer with a meaningful call to action and a consent card in the Alexa app for the customer to try setting another reminder.

Finally, I also wanted to check whether a reminder is set before I prompt the user to set a reminder. For that, we make a call to get all active reminders set by this skill. Because Slot Machine can set reminders for multiple tournaments on different days, this code checks through the full list of returned reminders to see if the day matches that of the next tournament for which we want to set a reminder.

Other Notes

The above code demonstrates how to set a reminder, check for active reminders, and handle the result from setting a reminder. This code works well if you are only handling reminders in response to an explicit user request (such as with my ReminderIntent), but what about my other use case, where I prompt the customer when they are exiting the skill? In this case, I keep a timestamp so I don’t bother the user more than once a week. There are, of course, many other ways that this could be handled such as combining or replacing this logic with a note that customers can set a reminder in the future by explicit request — or to mention this as part of the Help text — or even to mention it at the end of the tournament itself. This feature is new enough that I haven’t had an opportunity to play with these different options to determine which would be best, but the key is that any of these options should be considered with the customer in mind.

Adding Reminders to your Custom Alexa Skill was originally published in Hacker Noon on Medium, where people are continuing the conversation by highlighting and responding to this story.