Alexa Reminders API Reference

---

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

For more details on how reminders operate, see Alexa Reminders Overview and Alexa Reminders Guidelines.

• Alexa Reminders API endpoint and authorization
• In-session and out of session behavior for Alexa Reminders API
• Create a reminder
• Get a reminder
• Get all reminders
• Update a reminder
• Delete a reminder
• Reminder object
• How trigger times are calculated
• Error messages
• Subscribe to reminder events

Alexa Reminders API endpoint and authorization

You get the API endpoint 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. For this value, use the access token retrieved from Login with Amazon.

The id used in some operations refers to the id of the reminder. This id automatically generates when the reminder gets created.

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

You create (POST) reminders with an in-session access token – don't use an out-of-session token.

GET, UPDATE, and DELETE operations work with both in-session and out of session access tokens. For more details about using out of session access tokens, see Out of session interaction.

• New recurrence rules
• Deprecated recurrence rules

Delete a reminder

A 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

How trigger times are calculated

Skills can set reminders in absolute or relative time.

Set these values by using a trigger.type of either SCHEDULED_ABSOLUTE or SCHEDULED_RELATIVE.

Absolute calculations

Example: Your skill wants to set a reminder to a fixed pre-calculated time – for instance, to remind someone to take some medicine on June 1st at 7pm.

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

Relative calculations

Example: Your skill wants to set a reminder to a relative, duration-based time – for instance, to remind someone take medicine in one hour.

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

How time zones work for reminder times

Case 1: set a reminder in the time zone of the device

If your skill wants to set the reminder in the same time zone of the device, you don't have to set the timezoneId field.

The following example sets the reminder at 7 pm in the correct time zone of the device.

Case 2: Set a reminder in the time zone of the app

If your skill provides the date, time, and time zone of the desired reminder, you must set an appropriate timezoneId field for when the reminder should occur.

The following example sets a reminder for a reservation on June 1st at 7pm in New York.

Error messages

HTTP Status Code	Enum	Message
400	INVALID_REQUEST_TIME_FORMAT	Request 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.
	UNSUPPORTED_TRIGGER_RECURRENCE_INTERVAL	Recurrence pattern is valid but minimum interval between two occurrences is not supported.
	INVALID_ALERT_INFO	Alert info is missing locale / invalid locale format. Text string is too long.
	INVALID_TRIGGER_OFFSET	Invalid relative time offset.
	UNSUPPORTED_SCHEDULED_TIME_FORMAT	Unsupported trigger scheduled time format. Supported format is YYYY-MM-DDTHH:mm:ss.SSS/YYYY-MM-DDTHH:mm:ss/YYYY-MM-DDTHH:mm.
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.
	NOT_IN_SESSION	Reminders can only be created in session.
403	MAX_REMINDERS_EXCEEDED	Max limit of reminders on the device reached (for example, 500).
	DEVICE_NOT_SUPPORTED	Reminders are not supported on this device.
404	ALERT_NOT_FOUND	Alert does not exist.
409	MISSING_TIME_ZONE	Device has no time zone set.
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

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.

For more details on subscribing to reminder events, see Skill events in Alexa skills.

apiEndpoint value used in event

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

Reminder events in JSON format

Your skill can subscribe to reminder events. You set this up by configuring your skill.json manifest file. For more details on this process, see Use Events in Your Skill Service.

You can set up the following reminder events.

• REMINDER_STARTED
• REMINDER_CREATED
• REMINDER_DELETED
• REMINDER_UPDATED
• REMINDER_STATUS_CHANGED

ReminderStarted

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

ReminderCreated

Alexa generates the ReminderCreated event after creating a reminder. Alexa sends this event to the skill that created the reminder, not the user who used the skill.

ReminderDeleted

Alexa generates the ReminderDeleted event after the user deletes a reminder. Alexa sends this event to the skill that created the reminder.

ReminderUpdated

Alexa generates the ReminderUpdated event when a reminder updates. This event doesn't provide any details on the update, except for the current state of the reminder. To get further update details, the skill should use the Get all reminders API .

Possible updates include one of the following:

• Completed
• Turned on

Or, when a reminder:

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

ReminderStatusChanged

Alexa generates the ReminderStatusChanged event when the reminder status changes.

Possible statuses include one of the following:

• On
• Completed
• Deferred

---

---

Last updated: Nov 29, 2023