Alexa Reminders Overview


With the Alexa Reminders API, which is a set of RESTful APIs, your skill can create and manage reminders for your customers. 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. For more information, see Alexa Reminders API Reference and Alexa Reminders Guidelines.

Customer experience for reminders

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

Alexa "barges in" to whatever interaction a customer may be having with Alexa at that moment. This may be disruptive if the customer is not expecting this reminder. To protect customers from unexpected barge-ins, a skill must acquire two sets of permissions in order to create a reminder: a) Global Reminders Read/Write permission (which the skill requests from the user after skill enablement), and b) 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 may 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 when the reminder time will be and call out if this is a recurring reminder.

When a reminder is due to go off, the customer's Alexa-enabled device plays a brief tone, and then Alexa 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 cannot customize the voice delivery for the reminders. However, in your skill service, you can set whether the reminder should also enable a mobile phone notification.

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

If the customer has not 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 weekly basis, or on specific days.

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.

How to add reminders to your skill

If you have an existing Alexa custom skill, or are building a new custom skill, you can integrate with Alexa reminders by following these steps:

  • If you have created your skill in the developer console, go to the Build page, and select Permissions at the lower left. Toggle Reminders on. Your skill is now enabled to ask the user for reminders permissions.
  • Implement reminders capabilities in your skill service code.
  • Make sure your skill subscribes to reminders events, such as when a customer deletes or edits a reminder that your skill has previously set.
    • Use the Alexa Skill Management API (SMAPI) 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 information, see Subscribe to reminder events.
    • Implement handlers to consume and respond to reminder events.
  • The customer should receive a card in the Alexa app that indicates the reminder has been delivered. This card should follow this format:
Format for reminder card in the Alexa app

If you edit the skill manifest directly, make sure that it contains the alexa::alerts:reminders:skill:readwrite permission.

Manage permissions with an apiAccessToken

When your skill uses the Alexa Reminders API to create a reminder, your skill must provide an in-session ID where explicit customer permission was granted. If a skill is found to violate the permission policy, reminders access for the skill will be revoked. An out-of-session token cannot be used to create a reminder, but can be used to edit or delete a reminder.

If your skill does not have explicit customer permission, such as the first time a skill is invoked, it must obtain customer 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 (apiAccessToken) that encapsulates the permissions granted to your skill. Your skill service needs to retrieve this token for use when you call the API to create a reminder.

The apiAccessToken is nested in the System object, which is nested in the context object. To see the full body of the request, refer to Request Format.

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

The access token in an Authorization header in the format: Bearer ACCESS_TOKEN, where ACCESS_TOKEN is the value of the apiAccessToken field from the Alexa request message. Here is an example:

Authorization: Bearer AxThk...6fnLok

Thus, for Node.js:

accessToken = this.event.context.System.apiAccessToken

For more information, see Handling Requests Sent by Alexa.


Was this page helpful?

Last updated: Nov 29, 2023