Your Alexa Consoles
Sign In
Sign In

Alexa Reminders API Reference

Use the Alexa Reminders API to create and manage reminders from your skill. This reference describes the available operations for the Alexa Reminders API.

For more information, see Alexa Reminders Overview and Alexa Reminders Guidelines.

Alexa Reminders API endpoint and authorization

The API's endpoint is taken from the apiEndpoint value in the context object of the incoming request.

  • North America: https://api.amazonalexa.com

  • Europe: https://api.eu.amazonalexa.com

  • Far East: https://api.fe.amazonalexa.com

Each API request must have an Authorization header whose value should be the access token retrieved from Login with Amazon.

The id used in some operations refers to the id of the reminder, which is automatically generated when the reminder is created.

In-session and out of session behavior for Alexa Reminders API

Reminders can only be created using an in-session access token. However, the GET, UPDATE, and DELETE operations work with both in-session and out of session access tokens. See: Out of session interaction.

Create a reminder

A skill invokes this API to create a new reminder for the current skill.

Request

POST /v1/alerts/reminders

Header of the request

Content-length: << length in bytes >>
Authorization: Bearer <<access token>>
Content-Type: application/json

Body of the request (SCHEDULED_ABSOLUTE)

{
   "requestTime" : "2019-09-22T19:04:00.672",
   "trigger": {
        "type" : "SCHEDULED_ABSOLUTE",
        "scheduledTime" : "2019-09-22T19:00:00.000",
        "timeZoneId" : "America/Los_Angeles",
        "recurrence" : {                     
            "freq" : "WEEKLY",               
            "byDay": ["MO"]                 
        }
   },
   "alertInfo": {
        "spokenInfo": {
            "content": [{
                "locale": "en-US", 
                "text": "walk the dog"
            }]
        }
    },
    "pushNotification" : {                            
         "status" : "ENABLED"
    }
}

Body of the request (SCHEDULED_RELATIVE)

{
   "requestTime" : "2019-09-22T19:04:00.672",
   "trigger": {
        "type" : "SCHEDULED_RELATIVE",
        "offsetInSeconds" : "7200"
   },
   "alertInfo": {
        "spokenInfo": {
            "content": [{
                "locale": "en-US", 
                "text": "walk the dog"
            }]
        }
    },
    "pushNotification" : {                            
         "status" : "ENABLED"         
    }
}
Field Description Parameter
Type
requestTime Valid ISO 8601 format. Describes the time when event actually occurred. string
trigger Contains information about the trigger for a reminder. object
trigger.type Indicates type of trigger. SCHEDULED_ABSOLUTE or SCHEDULED_RELATIVE. enum
trigger.offsetInSeconds If trigger.type is set to SCHEDULED_RELATIVE, use this field to specify the time after which the reminder will ring (in seconds). integer
trigger.timeZoneId A string containing the ID of the time zone. See How time zones work. enum
trigger.recurrence Contains information about recurrence information for the reminder. object
trigger.recurrence.freq One of: WEEKLY, DAILY. Frequency type of the recurrence. enum
trigger.recurrence.byDay Specifies a day or list of days within a week. Use the first two letters of the weekday name. For example, a full week is [ "SU", "MO", "TU", "WE", "TH", "FR", "SA" ] enum
alertInfo Contains information about the alert. object
alertInfo.spokenInfo Contains information about the spoken content in the alert. object
alertInfo.spokenInfo.content Contains the content of the alert. object
alertInfo.spokenInfo.content.locale Locale in which value is specified. enum
alertInfo.spokenInfo.content.text Text used for display and spoken purposes. string
pushNotification Contains information about the push notification. object
pushNotification.status One of: ENABLED, DISABLED enum

Response

HTTP/1.1 200 OK

Body of the response

{
  "alertToken": "string",
  "createdTime": "2019-08-14T15:40:55.002Z",
  "updatedTime": "2019-08-14T15:40:55.002Z",
  "status": "ON",
  "version": "string",
  "href": "string"
}
Field Description Parameter Type
alertToken Unique id of this reminder alert. string
createdTime Valid ISO 8601 format - Created time of this reminder alert. string
updatedTime Valid ISO 8601 format - Last updated time of this reminder alert. string
status ON or COMPLETED. enum
version Version of this reminder alert. string
href URI to retrieve the created alert. string

Get a specified reminder

The skill invokes this API to get a specified reminder for the current skill.

Request

GET /v1/alerts/reminders/{id}

Response

The response includes a reminder object inside the alerts object.

HTTP/1.1 200 OK

{
  "totalCount": "string",
  "alerts": [
    {
      "alertToken": "string",
      "createdTime": "2019-08-14T15:47:48.386Z",
      "updatedTime": "2019-08-14T15:47:48.386Z",
      "status": "ON",
      "trigger": {
        "type": "SCHEDULED_ABSOLUTE",
        "scheduledTime": "2019-08-14T15:47:48.387Z",
        "offsetInSeconds": 0,
        "timeZoneId": "string",
        "recurrence": {
          "freq": "WEEKLY",
          "byDay": [
            "SU"
          ],
          "interval": 0
        }
      },
      "alertInfo": {
        "spokenInfo": {
          "content": [
            {
              "locale": "string",
              "text": "string"
            }
          ]
        }
      },
      "pushNotification": {
        "status": "ENABLED"
      },
      "version": "string"
    }
  ],
  "links": "string"
}

Get all reminders

A skill invokes this API to get all reminders for the skill. This includes completed reminders, which have a status of "OFF".

Request

GET /v1/alerts/reminders

Response

The response includes one or more reminder objects inside the alerts object.

HTTP/1.1 200 OK

{
  "totalCount": "string",
  "alerts": [
    {
      "alertToken": "string",
      "createdTime": "2019-08-14T16:03:38.811Z",
      "updatedTime": "2019-08-14T16:03:38.811Z",
      "status": "ON",
      "trigger": {
        "type": "SCHEDULED_ABSOLUTE",
        "scheduledTime": "2019-08-14T16:03:38.811Z",
        "offsetInSeconds": 0,
        "timeZoneId": "string",
        "recurrence": {
          "freq": "WEEKLY",
          "byDay": [
            "SU"
          ],
          "interval": 0
        }
      },
      "alertInfo": {
        "spokenInfo": {
          "content": [
            {
              "locale": "string",
              "text": "string"
            }
          ]
        }
      },
      "pushNotification": {
        "status": "ENABLED"
      },
      "version": "string"
    }
  ],
  "links": "string"
}

Update a reminder

The skill invokes this API to update a reminder for the current skill.

Request

PUT /v1/alerts/reminders/{id}

Body of the request

{
  "createdTime": "2019-08-14T15:53:12.919Z",
  "trigger": {
    "type": "SCHEDULED_ABSOLUTE",
    "scheduledTime": "2019-08-14T15:53:12.919Z",
    "offsetInSeconds": 0,
    "timeZoneId": "string",
    "recurrence": {
      "freq": "WEEKLY",
      "byDay": [
        "SU"
      ],
      "interval": 0
    }
  },
  "alertInfo": {
    "spokenInfo": {
      "content": [
        {
          "locale": "string",
          "text": "string"
        }
      ]
    }
  },
  "pushNotification": {
    "status": "ENABLED"
  }
}

Response

HTTP/1.1 200 OK

Body of the response

{
  "alertToken": "string",
  "createdTime": "2019-08-14T15:40:55.002Z",
  "updatedTime": "2019-08-14T15:40:55.002Z",
  "status": "ON",
  "version": "string",
  "href": "string"
}
Field Description Parameter Type
alertToken Unique id of this reminder alert. string
createdTime Valid ISO 8601 format - Created time of this reminder alert. string
updatedTime Valid ISO 8601 format - Last updated time of this reminder alert. string
status ON or COMPLETED. enum
version Version of this reminder alert. string
href URI to retrieve the created alert. string

Delete a reminder

The skill invokes this API to delete a specified reminder for the current skill. This operation only deletes active reminders, and not completed ones. The Alexa app shows completed reminders for three days after completion, after which they are automatically deleted.

Request

DELETE /v1/alerts/reminders/{id}

Response

HTTP/1.1 200 OK

Reminder object

Field Description Parameter
Type
requestTime Created time of this reminder alert in valid ISO 8601 format. string
trigger Required. Trigger information for reminder. object
trigger.type One of: SCHEDULED_ABSOLUTE, SCHEDULED_RELATIVE. A reminder may be set for a specified time, or relative to the requestTime as calculated by the offsetInSeconds. enum
trigger.scheduledTime Intended trigger time in valid ISO 8601 format. Used if the trigger.type is SCHEDULED ABSOLUTE. string
trigger.offsetInSeconds If trigger.type is SCHEDULED_RELATIVE, use this field to specify the time after which reminder will ring (in seconds) integer
trigger.timeZoneId Intended reminder’s time zone. See this list of time zones string
alertInfo Alert information for VUI/GUI presentation of the reminder object
alertInfo.spokenInfo Required. VUI presentation of the reminder. Spoken and display information is the same. object
alertInfo.spokenInfo.content Content of the spoken and displayed information. alertInfo.spokenInfo.content.text for at least one locale is mandatory. string
alertInfo.spokenInfo.content.locale Locale in which the spoken text is rendered. One of the supported locales for Alexa, such as en-US.
alertInfo.spokenInfo.content.text Spoken text in plain-text format. string
pushNotification Enable/disable push notifications of reminders to Alexa mobile apps. object
pushNotification.status One of: ENABLED, DISABLED. Default is ENABLED. enum

Calculation of trigger time

Skills can set reminders using either absolute or relative time by using a trigger.type of SCHEDULED_ABSOLUTE or SCHEDULED_RELATIVE.

Absolute calculations

Example: Your skill wants to set a reminder on June 1 at 7pm to take medicine. For a reminder that uses absolute time, scheduledTime is a mandatory field.

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

Relative calculations

Example: Your skill wants to set a duration-based reminder such as a reminder in one hour to take medicine.

"type" : "SCHEDULED_RELATIVE"
"offsetInSeconds" : 3600

This offset is relative to the requestedTime in the request.

How time zones work for reminder times

Case 1: Reminder in device's time zone

The skill wants to set the reminder in the device's time zone in which case the timezoneId field is not required.

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

This request sets the reminder in the device's time zone at 7 pm.

Case 2: Reminder in the time zone of the app

The skill provides the date, time, and time zone in which the reminder is set. For example: MySalon sets a reminder for a customer reservation on June 1 at 7pm in New York. Ensure that if you set the timezoneId value that you consider when the reminder will actually occur.

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

If the customer's device is in a time zone different from the app request, then Alexa translates the time into device's time zone for spoken and display purposes. Thus, if the customer's device is in PDT (Los Angeles), then the spoken time and display time is 4 pm in PDT.

Error messages

Http
Status Code		EnumMessage
400 INVALID_REQUEST_TIME_FORMATRequest time date format incorrect.
INVALID_TRIGGER Type and field do not match => SCHEDULED_ABSOLUTE has offsetInSeconds or SCHEDULED_RELATIVE has scheduledTime.
TRIGGER_SCHEDULED_TIME_IN_PAST Scheduled time is in the past.
INVALID_TRIGGER_SCHEDULED_TIME_FORMAT Date format is not supported.
INVALID_TRIGGER_TIME_ZONE Time zone is not valid.
INVALID_TRIGGER_RECURRENCE Recurrence pattern is invalid.
UNSUPPORTED_TRIGGER_RECURRENCE Recurrence pattern is valid but not currently supported.
INVALID_ALERT_INFO Alert info is missing locale / invalid locale format.
Text string is too long.
INVALID_TRIGGER_OFFSET Invalid relative time offset.
401 UNAUTHORIZED Token is valid but does not have appropriate permissions.
MISSING_BEARER_TOKEN Missing access token.
INVALID_BEARER_TOKEN Invalid / wrong access token.
EXPIRED_BEARER_TOKEN Access token expired.
403 MAX_REMINDERS_EXCEEDED Max limit of reminders on the device reached (for example, 500).
404 ALERT_NOT_FOUND Alert does not exist.
429 MAX_RATE_EXCEEDED Requests are throttled at the rate of 25 TPS per skill.
500 INTERNAL_SERVER_ERROR
503 SERVICE_UNAVAILABLE
504 DEVICE_NOT_REACHABLE Device not reachable/offline.

Subscribe to reminder events

See also: Skill events in Alexa skills

By subscribing to reminder events, your skill can be notified of these events without calling the Alexa Reminders API. Your skill can use account linking to integrate with an external app, and use notifications of these events to make changes in the app, such as by deleting or modifying the reminders in the app.

Any action that a skill takes as the result of a reminder event should consider the timestamp of the event, as notifications of events may arrive out of order. For example, if a reminder is updated twice, and the earlier update event arrives after the second update event, then the earlier update should be disregarded.

Alexa attempts to redeliver events if the skill service does not send an acknowledgment in response. The skill service cannot retrieve past events from Alexa, but must rely on the events being delivered.

apiEndpoint value used in event

This endpoint is https://api.amazonalexa.com.

Reminder events in JSON format

You can set up your skill to subscribe to reminder events by following Use Events in Your Skill Service to set up your skill.json manifest file.

The following reminder events are available:

ReminderStarted

Alexa generates this event when the reminder starts ringing. The skill service can then take corresponding actions at the trigger time.

{
  "version": "1.0",                                 
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"             
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",      
        "accessToken": "<access_token>",          
        "permissions": {
          "consentToken": "Atza|IgEB..."            
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"  
    }
  },
  "request": {
    "type": "Reminders.ReminderStarted",
    "requestId": "913e4588-62f9-4d5b",              
    "timestamp": "2017-09-15T01:46:14Z",            
    "body": {
      "alertToken": "<alert-token-value>",      
    }
  },
  "session": {
    "attributes": {}
  }
}

ReminderCreated

Alexa generates the ReminderCreated event when a reminder has been created. Alexa does not send this event to the creator of the reminder.

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",
        "accessToken": "<access_token>",
        "permissions": {
          "consentToken": "Atza|IgEB..."
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "Reminders.ReminderCreated",
    "requestId": "<requestId-value>",
    "timestamp": "2017-09-15T01:46:14Z",
    "body": {
      "alertToken": "<alert-token-value>"
    }
  },
  "session": {
    "attributes": {}
  }
}

ReminderDeleted

Alexa generates this event when a customer deletes a reminder.

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",
        "accessToken": "<access_token>",
        "permissions": {
          "consentToken": "Atza|IgEB..."
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "Reminders.ReminderDeleted",
    "requestId": "<requestId-value",
    "timestamp": "2017-09-15T01:46:14Z",
    "body": {
      "alertToken": "<alert-token-value>"
    }
  },
  "session": {
    "attributes": {}
  }
}

ReminderUpdated

Alexa generates the ReminderUpdated event when a reminder is:

  • Cancelled
  • Deferred
  • Completed
  • Paused
  • Resumed
  • Snoozed
  • Turned on

Or, when a reminder:

  • Has its trigger time updated.
  • Has its label updated.

THe event does not provide any details on the update, except for the current state of the reminder.

To get further details, the skill should use a Get a reminder API call to retrieve the details of the update.

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",
        "accessToken": "<access_token>",
        "permissions": {
          "consentToken": "Atza|IgEB..."
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "Reminders.ReminderUpdated",
    "requestId": "913e4588-62f9-4d5b",
    "timestamp": "2017-09-15T01:46:14Z",
    "body": {
      "status": "DEFERRED",
      "alertToken": "09d9d7df-05be-438c-veba"
    }
  },
  "session": {
    "attributes": {}
  }
}