The new Reminders API gives you the ability to create and manage reminders for customers as part of your Alexa skill experience. For example, you can using reminders in your skill help customers complete a task, like reminding them to make a reservation, or keep up with a daily routine, like reminding them to meditate.

To create a reminder using the Alexa Skills Kit (ASK) Software Development Kit (SDK) for Java, you should first check if the customer has granted permission to the skill to create a reminder for them. In the ASK SDK for Java, you can get this permissions information from the following HandlerInput:

Permissions permissions = input.getRequestEnvelope().getContext().getSystem().getUser().getPermissions();
if(null!=permissions){}

If the permissions object returns null, then the customer hasn’t provided the permissions to create the reminder. In this case, you can inform the customer how to grant permission to the skill to create a reminder. You can include these instructions for the customer and an askForPermissionsConsentCard that will take in a list of permissions that the skill needs. For creating a reminder, the permission needed is: alexa::alerts:reminders:skill:readwrite. The code snippet below shows how this can be implemented in your handle method for the intent:

String speechText = "In order for this skill to create a reminder, please grant permission using the card I sent to your Alexa app";
List<String> list = new ArrayList<>();
list.add("alexa::alerts:reminders:skill:readwrite");
return input.getResponseBuilder()
        .withSpeech(speechText)
        .withAskForPermissionsConsentCard(list)
        .build();

If the permissions object is not null, that means the customer has provided the permissions to create the reminder. In this example, we created a daily reminder at 7 p.m. reminding the customer to meditate.

if(null!=permissions && null!=permissions.getConsentToken()) {
    ReminderResponse reminderResponse = createReminder(input, locale, "Time To Meditate!");
    String speechText = "Ok, I will remind you to meditate everyday at 7 p.m.";
    return input.getResponseBuilder()
            .withSpeech(speechText)
            .withSimpleCard("Reminder Sample", speechText)
            .build();
}

For this example, we handle the creation of a reminder in the createReminder function (shown below) to which we pass the HandlerInput, Locale and a reminder label (the text we want the reminder to remind about).

private ReminderResponse createReminder(HandlerInput input, String locale, String reminderLabel) {

    SpokenText spokenText = SpokenText.builder()
            .withText(reminderLabel)
            .withLocale(locale)
            .build();

    AlertInfoSpokenInfo alertInfoSpokenInfo = AlertInfoSpokenInfo.builder()
            .addContentItem(spokenText)
            .build();

    AlertInfo alertInfo = AlertInfo.builder()
            .withSpokenInfo(alertInfoSpokenInfo)
            .build();

    LocalDateTime triggerTime = LocalDateTime.of(2019, 01, 10, 19, 00, 00);

    Recurrence recurrence = Recurrence.builder()
            .addByDayItem(RecurrenceDay.FR)
            .withFreq(RecurrenceFreq.WEEKLY)
            .build();

    Trigger trigger = Trigger.builder()
            .withType(TriggerType.SCHEDULED_ABSOLUTE)
            .withScheduledTime(triggerTime)
            .withRecurrence(recurrence)
            .withTimeZoneId("America/Los_Angeles")
            .build();

    PushNotification pushNotification = PushNotification.builder()
            .withStatus(PushNotificationStatus.ENABLED)
            .build();

    ReminderRequest reminderRequest = ReminderRequest.builder()
            .withAlertInfo(alertInfo)
            .withRequestTime(OffsetDateTime.now())
            .withTrigger(trigger)
            .withPushNotification(pushNotification)
            .build();

    return input.getServiceClientFactory().getReminderManagementService().createReminder(reminderRequest);
}

The locale can be obtained from the HandlerInput as shown below:

String locale = input.getRequestEnvelope().getRequest().getLocale();

Building the Recurrence Object

The recurrence object is built as follows:

Recurrence recurrence = Recurrence.builder()
        .addByDayItem(RecurrenceDay.FR)
        .withFreq(RecurrenceFreq.WEEKLY)
        .build()

Passing RecurrenceDay.FR to addByDayItem() in the example above, indicates that we want the reminder to recur on Fridays. Similarly, the frequency of the reminder – Weekly or Daily can be specified by passing RecurrenceFreq.WEEKLY or RecurrenceFreq.DAILY to withFreq() as shown above.

Building the Trigger Object

The Trigger object is built as follows:

Trigger trigger = Trigger.builder()
        .withType(TriggerType.SCHEDULED_ABSOLUTE)
        .withScheduledTime(triggerTime)
        .withRecurrence(recurrence)
        .withTimeZoneId("America/Los_Angeles")
        .build();

The triggerTime (should be of type LocalDateTime) is the time at which we want the skill to remind the users at a certain time. The Trigger Type can be SCHEDULED_ABSOLUTE or SCHEDULED_RELATIVE.

Note: Make sure to check out how time zones work for reminders here.

Detailed explanation and a complete list of parameters for creating a reminder can be found on the Reminders API Reference page.

When the customer uses the skill for the first time and has not granted the permission, they will be asked to look at the card sent to their Alexa app, which has instructions on how to grant permission. The card for this example will look like:

Once the customer grants permission, your skill can create the reminder.

Related Content

Check out the following resources to learn more about using the new Reminders API to make your Alexa skills more engaging for customers:

• Remind Customers of Important Tasks or Events with the Reminders API
• Reminders API Technical Documentation
• Guidelines for using the Reminders API
• Reminders API Reference