Alexa Reminders Overview

Your skill can create and manage reminders for your customers by using Alexa reminders. A skill requires explicit customer permission to create reminders and can only modify, edit, and delete reminders that the skill itself has created for that customer.

User experience for skill reminders

With the customer's permission, your skill can set a reminder for a predetermined time, and then, at this time, Alexa wakes up and reads the reminder to the customer.

Alexa "barges in" to whatever interaction a customer might be having with Alexa at that moment. If the customer isn't expecting this reminder, the interruption might be disruptive. To protect customers from unexpected barge-ins, a skill must acquire two sets of permissions to create a reminder:

  1. Global Reminders Read/Write permission, that the skill requests from the user after skill enablement.
  2. Explicit customer permission for setting each specific reminder.

Your skill should obtain explicit permission as part of the dialog that your skill has with the customer. For example, you might ask the customer, "Would you like me to remind you?" or "Do you want me to remind you of this?" The skill response must clarify to the customer about the reminder time, and include the reminder recurrence, if defined.

When a reminder is due to go off, Alexa plays a brief tone on the customer's Alexa-enabled device, and then says, "Here's your reminder….," along with label information. The reminder repeats twice unless the customer says, "Stop."

A sample uninterrupted reminder flow:

  • Alexa plays a brief tone at the reminder time.
  • Alexa says, "Here's your reminder. You have an upcoming reservation at Fizzy-Foo today at 8.00 PM. You have an upcoming reservation at Fizzy-Foo today at 8.00 PM."

You can't customize the voice delivery for the reminders. However, when you create the reminder, you can set whether the reminder should also enable a mobile notification.

The customer sees reminders in the Alexa app until three days after completion, after which the reminders are automatically deleted.

If the customer hasn't granted reminders permission to the skill, make sure that your skill gracefully informs the customer how to grant permissions and that the skill sends the customer a home card providing a link to the skill permissions page in the Alexa app.

Reminder types

Your skill can create a one-time or recurring reminder. If a recurring reminder, your skill can set the reminder to occur on a daily, weekly, monthly, or yearly basis, or on specific days.

How trigger times are calculated

Your skill can create a reminder that has an absolute time, which means it occurs at a specified time, or a reminder with a relative time, which means that it occurs a specified amount of time after another event.

Absolute calculations

Use absolute time to set a reminder to a fixed pre-calculated time, for example, to remind someone to take medicine on June 1, 2019 at 7 PM.

To set this reminder, use a SCHEDULED_ABSOLUTE reminder and a fixed value for the mandatory scheduledTime field.

"requestTime" : "2019-09-22T19:04:00.672",
   "trigger": {
        "type" : "SCHEDULED_ABSOLUTE",
        "scheduledTime" : "2019-06-01T19:00:00"
   }

Relative calculations

Use an offset to set a reminder to a relative, duration-based time, for example, to remind someone to take medicine in one hour.

To set this reminder, use a SCHEDULED_RELATIVE reminder and an offset in seconds. The ring time calculates by comparing the requestedTime to the offsetInSeconds that the skill sets.

   "requestTime" : "2019-09-22T19:04:00.672",
   "trigger": {
        "type" : "SCHEDULED_RELATIVE",
        "offsetInSeconds" : "7200"
   }

Setting time zones for absolute times

You can set a reminder in the time zone of the Alexa-enabled device, or in the time zone of your app or service.

To set a reminder in the same time zone of the device, include the scheduledTime. You don't have to set the timezoneId field. The following example sets the reminder at 7 PM in the time zone of the device.

"scheduledTime" : "2019-06-01T19:00:00"

To set a reminder in the time zone of the app, provide the absolute time and the time zone for when the reminder should occur. The following example sets a reminder for a reservation on June 1, 2019 at 7 PM in New York.

"scheduledTime" : "2019-06-01T19:00:00"
"timezoneId" : "America/New_York"

Steps to add reminders to your skill

Complete the following steps to integrate your custom skill with Alexa reminders.

To add reminders to your custom skill

  1. If you created your skill in the developer console, to ask the user for reminders permissions, on the Build page, in the left pane, select TOOLS > Permissions or PERMISSIONS, and then toggle Reminders.
    Or, if you edit the skill manifest directly, add the alexa::alerts:reminders:skill:readwrite permission.
  2. Implement reminders capabilities in your skill service code.
    • Use the Reminders REST API to create a new reminder skill or to update your existing custom skill to subscribe to reminder events.
    • Request Alexa reminders permission from the customer and use the APIs to read and update Alexa reminders. A skill can only access reminders that the skill itself has created.
    • Follow the instructions to Use Events in Your Skill Service to set up your skill.json manifest file for reminder events. For more details, see Reminder events.
    • Implement handlers to consume and respond to reminder events.
  3. Send a card to the Alexa app that indicates the reminder was delivered. For more details, see Include a Card in Your Skill's Response.
    The following card shows an example reminder.
Format for reminder card in the Alexa app

Manage permissions with an apiAccessToken

When your skill uses the Reminders API to create a reminder, your skill must provide an in-session ID where explicit customer permission was granted. If a skill violates the permission policy, reminders access for the skill is revoked. You can't use an out-of-session token to create a reminder, but you can use the out-of-session token to edit or delete a reminder.

If your skill doesn't have explicit customer permission when the customer invokes your skill, it must obtain permission either by following a voice permissions workflow, or by sending a permissions card to the customer. To set up voice permissions, see Set Up Voice Permissions for Reminders. To set up permissions by card, see Permissions card for requesting customer consent. The scope for reminders is alexa::alerts:reminders:skill:readwrite.

Each request sent to your skill includes an API access token that encapsulates the permissions granted to your skill. Retrieve this token for use when you call the API to create or edit a reminder.

The following example shows the context.System.apiAccessToken in the request message. For the full body of the request, see Request Format.

{
  "context": {
    "System": {
      "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.amazonalexa.com",
      "device": {
        "deviceId": "string-identifying-the-device",
        "supportedInterfaces": {}
      },
      "application": {
        "applicationId": "string"
      },
      "user": {}
    }
  }
}

The following example shows how to get the access token in Node.js.

accessToken = this.event.context.System.apiAccessToken
Was this page helpful?

Last updated: May 22, 2024