Reminders API


Use the Alexa Reminders API v2 to create and manage reminders on managed devices in your property. You can configure the text in the reminder, and Alexa speaks the text from the device at the specific time you schedule. Use reminders to build voice experiences that help users remember daily tasks, events, schedules, or any other items they want to remember at a later time.

The API uses JSON over HTTP with OAuth authentication and provides capabilities such as scheduling absolute reminders (for example, a reminder at 3 PM) or relative reminders (for example, a reminder in 10 minutes), updating and deleting reminders, and listing all reminders for a given device. You can also schedule one-time and recurring reminders.

API endpoint

In the request header, set Host to the following, depending on the region of your organization:

Country Endpoint

CA, US

https://api.amazonalexa.com

DE, ES, FR, IT, UK

https://api.eu.amazonalexa.com

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

Operations

The Reminders API includes the following operations.

Operation HTTP method and URI

Create a reminder

POST /v2/alerts/reminders

Get a reminder

GET /v2/alerts/reminders/{reminderId}

Update a reminder

PUT /v2/alerts/reminders/{reminderId}

Delete a reminder

DELETE /v2/alerts/reminders/{reminderId}

Get all reminders on an endpoint

GET /v2/alerts/reminders?recipient.id=amzn1.alexa.endpoint.did.<endpointId>&recipient.type=Endpoint&owner=~caller

Create a reminder

Creates a new reminder.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES

US, UK, FR, CA, IT, DE, ES

US

Request

To create a reminder, you make a POST request.

Request header example

POST /v2/alerts/reminders HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {Access Token}

Request path and header parameters

Parameter Located in Description Type Required

access_token

Header

LWA access token. For details, see Authentication.

String

Yes

Content-Type

Header

application/json

String

Yes

Request body examples

Absolute reminder example

The following example creates a single reminder that triggers at 4:30 PM on June 21, 2024.

{
  "recipients": [
    {
      "type": "Endpoint",
      "id": "amzn1.alexa.endpoint.did.1234"
    }
  ],
  "reminder": {
    "trigger": {
      "type": "SCHEDULED_ABSOLUTE",
      "scheduledTime": "2024-06-21T16:30:00.000",
      "timeZoneId": "America/Los_Angeles"
    },
    "alertInfo": {
      "spokenInfo": {
        "content": [
          {
            "locale": "en-US",
            "text": "Bingo starts at five p.m.",
            "ssml": "<speak>Bingo starts at five p.m.</speak>"
          }
        ]
      }
    }
  }
}

Recurring reminder example

The following example creates a reminder that triggers at 4:30 PM on the fifth day of each month, starting in June 2024 and ending in September 2024.

{
  "recipients": [
    {
      "type": "Endpoint",
      "id": "amzn1.alexa.endpoint.did.1234"
    }
  ],
  "reminder": {
    "trigger": {
      "type": "SCHEDULED_ABSOLUTE",
      "recurrence": {
        "startDateTime": "2024-06-01T00:00:00.000",
        "endDateTime": "2024-09-30T00:00:00.000",
        "recurrenceRules": [
          "FREQ=MONTHLY;BYMONTHDAY=5;BYHOUR=16;BYMINUTE=30;INTERVAL=1;"
        ]
      }
    },
    "alertInfo": {
      "spokenInfo": {
        "content": [
          {
            "locale": "en-US",
            "text": "Bingo starts at five p.m.",
            "ssml": "<speak>Bingo starts at five p.m.</speak>"
          }
        ]
      }
    }
  }
}

Relative reminder example

The following example creates a reminder that triggers 30 minutes after the specified request time of 2024-06-21T22:30:00. This request time is in UTC. For a device with the time zone "America/Los_Angeles", this reminder is scheduled for June 21, 2024 at 4 PM. For a device with the time zone "America/Denver," this reminder is scheduled for June 21, 2024 at 5 PM.

{
  "recipients": [
    {
      "type": "Endpoint",
      "id": "amzn1.alexa.endpoint.did.1234"
    }
  ],
  "reminder": {
    "requestTime": "2024-06-21T22:30:00",
    "trigger": {
      "type": "SCHEDULED_RELATIVE",
      "offsetInSeconds": "1800"
    },
    "alertInfo": {
      "spokenInfo": {
        "content": [
          {
            "locale": "en-US",
            "text": "Bingo starts at five p.m.",
            "ssml": "<speak>Bingo starts at five p.m.</speak>"
          }
        ]
      }
    }
  }
}

Request body properties

Property Description Type Required

recipients

Array of recipients to which to apply this reminder. You can provide exactly one recipient.

Array of objects

Yes

recipients[].type

Type of recipient.
Accepted values: Endpoint.

Enum

Yes

recipients[].id

Unique identifier for the recipient. This must be an endpoint ID.

String

Yes

reminder

Contents of the reminder.

Object

Yes

reminder.requestTime

Specifies the date and time to use when scheduling a relative reminder, specified in coordinated universal time (UTC). The API applies the offsetInSeconds to the requestTime to calculate the trigger time for a relative reminder. When not provided, defaults to the current date and time. Specify the requestTime in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

Provide the requestTime in UTC time, not in the local time zone of the device. The API then uses the time zone of the device to calculate the reminder time. For example, assume the requestTime is 2024-06-21T22:30:00 and the offsetInSeconds is 1800 (30 minutes). For a device with the time zone "America/Los_Angeles", this reminder is scheduled for June 21, 2024 at 4 PM. For a device with the time zone "America/Denver," this reminder is scheduled for June 21, 2024 at 5 PM.

String

No

reminder.trigger

Contains information about the trigger for a reminder.

Object

Yes

reminder.trigger.type

Indicates type of trigger.
Accepted values: SCHEDULED_ABSOLUTE or SCHEDULED_RELATIVE.

Enum

Yes

reminder.trigger.offsetInSeconds

Applies when trigger.type is SCHEDULED_RELATIVE. Specifies the number of seconds after the requestTime to play the reminder.

Not applicable when the trigger.type is SCHEDULED_ABSOLUTE.

Integer

Yes when the trigger.type is SCHEDULED_RELATIVE.

reminder.trigger.scheduledTime

Trigger date and time for a single reminder scheduled at an absolute time (SCHEDULED_ABSOLUTE). Provide the date and time in ISO 8601 format. For example, 2024-06-24T18:00:00.000 for June 24, 2024 at 6 PM.

  • Not applicable when trigger.type is SCHEDULED_RELATIVE.
  • Ignored for recurring reminders. Use the trigger.recurrence.recurrenceRules property to specify the time for a recurring reminder.

String

Yes when the trigger.type is SCHEDULED_ABSOLUTE.

reminder.trigger.timeZoneId

A string containing the ID of the time zone. For valid values, see List of tz database time zones identifiers. If you don't provide a time zone, the reminder defaults to use the time zone of the device. Not applicable when the trigger.type is SCHEDULED_RELATIVE.

For details about time zones, see Time zones for absolute times.

Enum

No

reminder.trigger.recurrence

Specifies recurrence information for reminders that repeat at regular intervals.

Not applicable when the trigger.type is SCHEDULED_RELATIVE.

Object

No

reminder.trigger.recurrence.startDateTime

Optional. The start of the recurrence pattern. Defined with both the date and time in ISO 8601 format. When not provided, defaults to the current date and time.

Enum

No

reminder.trigger.recurrence.endDateTime

Optional. The end of the recurrence pattern. Defined with both the date and time in ISO 8601 format. When not provided, the recurring reminder continues indefinitely.

Enum

No

reminder.trigger.recurrence.recurrenceRules

The recurrence pattern for a repeating alert, in the RRULE format. Supported Values: FREQ, BYMONTHDAY, BYDAY, BYHOUR, BYMINUTE, BYSECOND, and INTERVAL

The supported FREQ RRULE patterns are FREQ=DAILY, FREQ=WEEKLY, FREQ=MONTHLY, and FREQ=YEARLY

  • The minimum interval between two recurrence values is one hour for the en-US locale and four hours for all other supported locales.
  • The maximum interval for DAILY, WEEKLY and MONTHLY patterns is 31 days.
  • The maximum interval for YEARLY pattern is one year.

If these constraints aren't met, the request returns a 400 error.

String[]

Yes

reminder.alertInfo

Specifies information about the reminder.

Object

Yes

reminder.alertInfo.spokenInfo

Contains information about the spoken content in the reminder.

Object

Yes

reminder.alertInfo.spokenInfo.content

Contains the content of the reminder.

Object[]

Yes

reminder.alertInfo.spokenInfo.content[].locale

Defines the locale and language for the reminder text.

String

Yes

reminder.alertInfo.spokenInfo.content[].ssml

Text used for spoken content, in Speech Synthesis Markup Language (SSML) format. If you don't provide a value for this field, alertInfo.spokenInfo.content.text handles both text and spoken content. Reminders supports the SSML speak tag.

String

No

reminder.alertInfo.spokenInfo.content[].text

Default text used for display and spoken content. If you provide a value in the ssml property, the text property is used for display only.

String

Yes

Time zones for absolute times

When a reminder trigger is set to an absolute time using the scheduledTime property, the reminder plays at either the time zone of the device, or a specific time zone you define in the request:

  • To set a reminder in the same time zone of the device, set the scheduledTime property and leave the timeZoneId field unset.
  • To set a reminder in a specific the time zone, set both the scheduledTime and timeZoneId properties.

Response

For a well-formed request, the API returns HTTP 202 Accepted and a response body where the type property indicates whether the reminder was successfully created. If an error occurred, the response body contains at status property with the error code and human readable message.

Response body examples

Success case

{
  "type": "ALL_SUCCESS",
  "message": "All reminders created successfully.",
  "successResults": [
    {
      "id": "amzn1.alexa.endpoint.did.1234",
      "reminderId": "<reminderId>"
    }
  ],
  "errors": []
}

Failed case

{
  "type": "ALL_FAILED",
  "message": "All reminders failed to created.",
  "successResults": [],
  "errors": [
    {
      "id": "amzn1.alexa.endpoint.did.1234",
      "status": 400,
      "errorCode": "DEVICE_NOT_SUPPORTED",
      "errorDescription": "Reminders are not supported on this device."
    }
  ]
}

Response headers

Property Description Type

Content-Type

Contains application/json

String

X-Amzn-RequestId

A UUID generated for the individual request.

String

Response body properties

Property Description Type

type

Type of response.
Possible values: ALL_SUCCESS, ALL_FAILED.

Enum

message

Detailed description of the result.

String

successResults[]

List of endpoints where the reminder was successfully created.

Array of objects

successResults[].id

The ID of the recipient for the reminder.

String

successResults[].reminderId

The ID of the reminder.

String

errors[]

List of endpoints where creating the reminder failed.

Array of objects

errors[].id

The ID of the recipient for the reminder.

String

errors[].status

Error status code for the failed reminder.

String

errors[].errorCode

Short error code string.

String

errors[].errorDescription

Detailed description of the error.

String

HTTP status codes

Status Type Message

400

INVALID_INPUT_TIME_FORMAT

Request time date format incorrect.

400

INVALID_TRIGGER

Type and field don't match => SCHEDULED_ABSOLUTE has offsetInSeconds or SCHEDULED_RELATIVE has scheduledTime.

400

TRIGGER_SCHEDULED_TIME_IN_PAST

Scheduled time is in the past.

400

INVALID_TRIGGER_SCHEDULED_TIME_FORMAT

Date format isn't supported.

400

INVALID_TRIGGER_TIME_ZONE

Time zone isn't valid.

400

INVALID_TRIGGER_RECURRENCE

Recurrence pattern is invalid.

400

UNSUPPORTED_TRIGGER_RECURRENCE

Recurrence pattern is valid but not currently supported.

400

UNSUPPORTED_TRIGGER_RECURRENCE_INTERVAL

Recurrence pattern is valid but minimum interval between two occurrences isn't supported.

400

INVALID_ALERT_INFO

Alert info is missing locale / invalid locale format. Text string is too long.

400

INVALID_TRIGGER_OFFSET

Invalid relative time offset.

400

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.

400

INVALID_INPUT

Invalid input error. Check the arguments and try again.

400

INVALID_RECIPIENT_ID

Recipient ID not valid

400

INVALID_RECIPIENT_TYPE

Recipient type isn't supported

400

DEVICE_NOT_REACHABLE

Device not reachable/offline.

A directive to create the reminder is sent upon invocation if the reminder is set to go off within seven days.

400

DEVICE_NOT_SUPPORTED

Reminders aren't supported on this device.

400

TOO_MANY_RECIPIENTS

The number of recipients has exceeded the allowable threshold of 1. The Reminders API doesn't currently support bulk reminders.

401

UNAUTHORIZED

The incoming request is missing a valid access token in the Authorization HTTP Header. The token might be malformed or have expired.

403

MAX_REMINDERS_EXCEEDED

Max limit of reminders on the device reached.

403

FORBIDDEN

The user doesn't have permission to perform this operation.

409

MISSING_TIME_ZONE

Device has no time zone set.

429

MAX_RATE_EXCEEDED

The request was throttled.

500

INTERNAL_SERVER_ERROR

Get a reminder

Retrieve a reminder by ID.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES

US, UK, FR, CA, IT, DE, ES

US

Request

To get a reminder, make a GET request with the reminderId.

Request header example

GET /v2/alerts/reminders/{reminderId}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {Access Token}

Request path and header parameters

Parameter Located in Description Type Required

access_token

Header

LWA access token. For details, see Authentication.

String

Yes

Content-Type

Header

application/json

String

Yes

reminderId

Path

ID for the reminder to retrieve.

String

Yes

Request body example

The request has no body.

Response

A successful response returns HTTP/1.1 200 and a response body with the reminder.

Response body example

Single, absolute scheduled reminder

{
    "recipient": {
        "id": "amzn1.alexa.endpoint.did.1234",
        "type": "Endpoint"
    },
    "reminder": {
        "reminderId": "b4ebac8b...",
        "createdTime": "2024-06-21T23:24:44.931Z",
        "updatedTime": "2024-06-21T23:24:45.066Z",
        "trigger": {
            "type": "SCHEDULED_ABSOLUTE",
            "scheduledTime": "2024-06-21T18:00:00.000",
            "timeZoneId": "America/Denver",
            "offsetInSeconds": 0
        },
        "status": "ON",
        "alertInfo": {
            "spokenInfo": {
                "content": [
                    {
                        "locale": "en-US",
                        "text": "Bingo starts at five p.m.",
                        "ssml": "<speak>Bingo starts at five p.m.</speak>"
                    }
                ]
            }
        },
        "version": "2"
    }
}

Recurring reminder

{
    "recipient": {
        "id": "amzn1.alexa.endpoint.did.1234",
        "type": "Endpoint"
    },
    "reminder": {
        "reminderId": "aebbb725...",
        "createdTime": "2024-06-21T23:31:53.722Z",
        "updatedTime": "2024-06-21T23:31:53.957Z",
        "trigger": {
            "type": "SCHEDULED_ABSOLUTE",
            "scheduledTime": "2024-07-05T16:30:00.000",
            "timeZoneId": "America/Denver",
            "offsetInSeconds": 0,
            "recurrence": {
                "startDateTime": "2024-06-01T00:00:00.000-06:00",
                "endDateTime": "2024-09-30T00:00:00.000-06:00",
                "recurrenceRules": [
                    "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=5;BYHOUR=16;BYMINUTE=30"
                ]
            }
        },
        "status": "ON",
        "alertInfo": {
            "spokenInfo": {
                "content": [
                    {
                        "locale": "en-US",
                        "text": "Bingo starts at five p.m.",
                        "ssml": "<speak>Bingo starts at five p.m.</speak>"
                    }
                ]
            }
        },
        "version": "3"
    }
}

Relative reminder

{
  "recipient": {
    "id": "amzn1.alexa.endpoint.did.1234",
    "type": "Endpoint"
  },
  "reminder": {
    "reminderId": "a64744c5...",
    "createdTime": "2024-06-21T20:15:57.272Z",
    "updatedTime": "2024-06-21T20:15:57.425Z",
    "trigger": {
      "type": "SCHEDULED_RELATIVE",
      "scheduledTime": "2024-06-21T14:17:57.235",
      "timeZoneId": "America/Denver",
      "offsetInSeconds": 120
    },
    "status": "ON",
    "alertInfo": {
      "spokenInfo": {
        "content": [
          {
            "locale": "en-US",
            "text": "Bingo starts at 5pm",
            "ssml": "<speak> Bingo starts at five p.m.</speak>"
          }
        ]
      }
    },
    "version": "3"
  }
}

Response body properties

Property Description Type

recipient

Recipient for this reminder.

Object

recipient.type

The type of the recipient.
Possible values: Endpoint.

Enum

recipient.id

Unique identifier for the recipient. This is always an endpoint ID.

String

reminder

Contents of the reminder.

Object

reminder.reminderId

Unique ID of this reminder alert.

String

reminder.createdTime

Created time of this reminder in ISO 8601 format.

String

reminder.updatedTime

Last updated time of this reminder in ISO 8601 format.

String

reminder.status

Indicates the current status of the reminder.
Possible values:

  • ON – This is an active reminder that will play in the future.
  • COMPLETED – The reminder has already triggered. Completed reminders are deleted after three days.

Enum

reminder.version

Version of this reminder alert. Version numbers are incremented upon update.

String

reminder.trigger

Contains information about the trigger for the reminder.

Object

reminder.trigger.type

Indicates type of trigger.
Possible values: SCHEDULED_ABSOLUTE or SCHEDULED_RELATIVE.

Enum

reminder.trigger.offsetInSeconds

Applies when the trigger.type is to SCHEDULED_RELATIVE. Specifies the number of seconds after requestTime to play the reminder.

Integer

reminder.trigger.scheduledTime

Trigger date and time of the reminder in ISO 8601 format.

  • For a relative reminder, this field contains the calculated trigger time based on the requestTime and offsetInSeconds provided when creating the reminder.
  • For a recurring reminder, this field contains either the next trigger date and time, or the most recent trigger date and time, based on the recurrence rules.

    There is an expected delay between when an instance of the recurring reminder is delivered and when the device schedules the next instance. During this delay, the scheduledTime returns the most recent trigger date and time and not the future time. For longer recurrence intervals, the device schedules the next instance in three to four hours. For shorter intervals, the scheduling occurs in under an hour.

String

reminder.trigger.timeZoneId

A string containing the ID of the time zone. For details about time zones, see Time zones for absolute times.

Enum

reminder.trigger.recurrence

Contains recurrence information for reminders that repeat at regular intervals.

Object

reminder.trigger.recurrence.startDateTime

The start of the recurrence pattern. Includes both the date and time.

String

reminder.trigger.recurrence.endDateTime

The end of the recurrence pattern. Returns an empty string for reminders that don't have a defined end time and therefore repeat indefinitely.

String

reminder.trigger.recurrence.recurrenceRules

The recurrence pattern for a repeating reminder, in the RRULE format.

String

reminder.alertInfo

Contains information about the reminder.

Object

reminder.alertInfo.spokenInfo

Contains information about the spoken content in the reminder.

Object

reminder.alertInfo.spokenInfo.content

Contains the content of the reminder. There can be multiple entries because the caller might have specified different reminders for different locales.

Array of objects

reminder.alertInfo.spokenInfo.content.locale

Locale for the reminder content.

String

reminder.alertInfo.spokenInfo.content.text

Default text used for display and spoken content.

String

reminder.alertInfo.spokenInfo.content.ssml

Text used for spoken content, in Speech Synthesis Markup Language (SSML) format.

String

HTTP status codes

Status Type Message

400

INVALID_REMINDER_ID

The provided reminder ID is invalid.

401

UNAUTHORIZED

The request is missing a valid access token in the Authorization HTTP Header. The token might be malformed or have expired.

403

FORBIDDEN

The user doesn't have permission to perform this operation.

404

REMINDER_NOT_FOUND

Reminder doesn't exist.

429

MAX_RATE_EXCEEDED

The request was throttled

500

INTERNAL_SERVER_ERROR

Example 404 response body

HTTP/1.1 404 Not Found 
Content-Type: application/json 
X-Amzn-RequestId: \<UUID generated for this particular request\>

{  
    "type": "REMINDER_NOT_FOUND",
    "message": "Reminder does not exist."
}

Update a reminder

Updates a reminder.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES

US, UK, FR, CA, IT, DE, ES

US

Request

To update a reminder, make a PUT call with the reminderId and a request body. You must include the full reminder object with the trigger and alertInfo objects.

For example, if you want to change the reminder text, but keep the original scheduled time, set the text and ssml properties to the new text, and set the values in the trigger object to the same values you used when creating the reminder.

Request header example

PUT /v2/alerts/reminders/{reminderId}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {Access Token}

Request header parameters

Parameter Located in Description Type Required

access_token

Header

LWA access token. For details, see Authentication.

String

Yes

Content-Type

Header

application/json

String

Yes

reminderId

Path

ID for the reminder to update.

String

Yes

Request body example

{
  "recipient": {
    "type": "Endpoint",
    "id": "amzn1.alexa.endpoint.did.1234"
  },
  "reminder": {
    "trigger": {
      "type": "SCHEDULED_ABSOLUTE",
      "timeZoneId": "America/Los_Angeles",
      "recurrence": {
        "startDateTime": "2019-05-10T6:00:00.000",
        "endDateTime": "2019-08-10T10:00:00.000",
        "recurrenceRules": [
          "FREQ=MONTHLY;BYMONTHDAY=5;BYHOUR=10;INTERVAL=1;"
        ]
      }
    },
    "alertInfo": {
      "spokenInfo": {
        "content": [
          {
            "locale": "en-US",
            "text": "Bingo starts at 5pm",
            "ssml": "<speak> Bingo starts at five p.m.</speak>"
          }
        ]
      }
    }
  }
}

Request body properties

Property Description Type Required

recipient

Recipient for the reminder. Provide an object with the type and id.

Object

Yes

recipient.type

Type of recipient.
Accepted values: Endpoint.

Enum

Yes

recipient.id

Unique identifier for the recipient. This must be an endpoint ID.

String

Yes

reminder

Contents of the reminder.

Object

Yes

reminder.requestTime

Specifies the date and time to use when scheduling a relative reminder, specified in coordinated universal time (UTC). The API applies the offsetInSeconds to the requestTime to calculate the trigger time for a relative reminder. When not provided, defaults to the current date and time. Specify the requestTime in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

Provide the requestTime in UTC time, not in the local time zone of the device. The API then uses the time zone of the device to calculate the reminder time. For example, assume the requestTime is 2024-06-21T22:30:00 and the offsetInSeconds is 1800 (30 minutes). For a device with the time zone "America/Los_Angeles", this reminder is scheduled for June 21, 2024 at 4 PM. For a device with the time zone "America/Denver," this reminder is scheduled for June 21, 2024 at 5 PM.

String

No

reminder.trigger

Contains information about the trigger for a reminder.

Object

Yes

reminder.trigger.type

Indicates type of trigger.
Accepted values: SCHEDULED_ABSOLUTE or SCHEDULED_RELATIVE.

Enum

Yes

reminder.trigger.offsetInSeconds

Applies when trigger.type is SCHEDULED_RELATIVE. Specifies the number of seconds after the requestTime to play the reminder.

Not applicable when the trigger.type is SCHEDULED_ABSOLUTE.

Integer

Yes when the trigger.type is SCHEDULED_RELATIVE.

reminder.trigger.scheduledTime

Trigger date and time for a single reminder scheduled at an absolute time (SCHEDULED_ABSOLUTE). Provide the date and time in ISO 8601 format. For example, 2024-06-24T18:00:00.000 for June 24, 2024 at 6 PM.

  • Not applicable when trigger.type is SCHEDULED_RELATIVE.
  • Ignored for recurring reminders. Use the trigger.recurrence.recurrenceRules property to specify the time for a recurring reminder.

String

Yes when the trigger.type is SCHEDULED_ABSOLUTE.

reminder.trigger.timeZoneId

A string containing the ID of the time zone. For valid values, see List of tz database time zones identifiers. If you don't provide a time zone, the reminder defaults to use the time zone of the device. Not applicable when the trigger.type is SCHEDULED_RELATIVE.

For details about time zones, see Time zones for absolute times.

Enum

No

reminder.trigger.recurrence

Specifies recurrence information for reminders that repeat at regular intervals.

Not applicable when the trigger.type is SCHEDULED_RELATIVE.

Object

No

reminder.trigger.recurrence.startDateTime

Optional. The start of the recurrence pattern. Defined with both the date and time in ISO 8601 format. When not provided, defaults to the current date and time.

Enum

No

reminder.trigger.recurrence.endDateTime

Optional. The end of the recurrence pattern. Defined with both the date and time in ISO 8601 format. When not provided, the recurring reminder continues indefinitely.

Enum

No

reminder.trigger.recurrence.recurrenceRules

The recurrence pattern for a repeating alert, in the RRULE format. Supported Values: FREQ, BYMONTHDAY, BYDAY, BYHOUR, BYMINUTE, BYSECOND, and INTERVAL

The supported FREQ RRULE patterns are FREQ=DAILY, FREQ=WEEKLY, FREQ=MONTHLY, and FREQ=YEARLY

  • The minimum interval between two recurrence values is one hour for the en-US locale and four hours for all other supported locales.
  • The maximum interval for DAILY, WEEKLY and MONTHLY patterns is 31 days.
  • The maximum interval for YEARLY pattern is one year.

If these constraints aren't met, the request returns a 400 error.

String[]

Yes

reminder.alertInfo

Specifies information about the reminder.

Object

Yes

reminder.alertInfo.spokenInfo

Contains information about the spoken content in the reminder.

Object

Yes

reminder.alertInfo.spokenInfo.content

Contains the content of the reminder.

Object[]

Yes

reminder.alertInfo.spokenInfo.content[].locale

Defines the locale and language for the reminder text.

String

Yes

reminder.alertInfo.spokenInfo.content[].ssml

Text used for spoken content, in Speech Synthesis Markup Language (SSML) format. If you don't provide a value for this field, alertInfo.spokenInfo.content.text handles both text and spoken content. Reminders supports the SSML speak tag.

String

No

reminder.alertInfo.spokenInfo.content[].text

Default text used for display and spoken content. If you provide a value in the ssml property, the text property is used for display only.

String

Yes

Response

A successful response returns HTTP/1.1 204 No Content with no response body. If an error occurs, the response includes a response body with the error information.

Response body example

The following example shows the response body for an error response.

{  
    "type": "INVALID_INPUT_TIME_FORMAT",
    "message": "Request time date format incorrect."
}

Response body properties

Parameter Description Type

type

Short description.

Enum

message

Detailed description of the result.

String

HTTP status codes

Status Type Message

400

INVALID_INPUT_TIME_FORMAT

Request time date format incorrect.

400

INVALID_TRIGGER

Type and field don't match => SCHEDULED_ABSOLUTE has offsetInSeconds or SCHEDULED_RELATIVE has scheduledTime.

400

TRIGGER_SCHEDULED_TIME_IN_PAST

Scheduled time is in the past.

400

INVALID_TRIGGER_SCHEDULED_TIME_FORMAT

Date format isn't supported.

400

INVALID_TRIGGER_TIME_ZONE

Time zone isn't valid.

400

INVALID_TRIGGER_RECURRENCE

Recurrence pattern is invalid.

400

UNSUPPORTED_TRIGGER_RECURRENCE

Recurrence pattern is valid but not currently supported.

400

UNSUPPORTED_TRIGGER_RECURRENCE_INTERVAL

Recurrence pattern is valid but minimum interval between two occurrences isn't supported.

400

INVALID_ALERT_INFO

Alert info is missing locale / invalid locale format. Text string is too long.

400

INVALID_TRIGGER_OFFSET

Invalid relative time offset.

400

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.

400

INVALID_INPUT

Invalid input error. Check the arguments and try again.

400

INVALID_RECIPIENT_ID

Recipient ID not valid

400

INVALID_RECIPIENT_TYPE

Recipient type isn't supported

400

DEVICE_NOT_REACHABLE

Device not reachable/offline.

A directive to create the reminder is sent upon invocation if the reminder is set to go off within seven days.

400

DEVICE_NOT_SUPPORTED

Reminders aren't supported on this device.

400

TOO_MANY_RECIPIENTS

The number of recipients has exceeded the allowable threshold of 1. The Reminders API doesn't currently support bulk reminders.

401

UNAUTHORIZED

The incoming request is missing a valid access token in the Authorization HTTP Header. The token might be malformed or have expired.

403

MAX_REMINDERS_EXCEEDED

Max limit of reminders on the device reached.

403

FORBIDDEN

The user doesn't have permission to perform this operation.

404

REMINDER_NOT_FOUND

Reminder to update doesn't exist.

409

MISSING_TIME_ZONE

Device has no time zone set.

409

VERSION_CONFLICT

The given version doesn't match latest version. This could occur if there are two concurrent updates for the same reminder.

429

MAX_RATE_EXCEEDED

The request was throttled

500

INTERNAL_SERVER_ERROR

Delete a reminder

Deletes the specified reminder.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES

US, UK, FR, CA, IT, DE, ES

US

Request

To delete a reminder, make a PUT call with the reminderId for the reminder to delete.

Request header example

DELETE /v2/alerts/reminders/{reminderId}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {Access Token}

Request header parameters

Parameter Located in Description Type Required

access_token

Header

LWA access token. For details, see Authentication.

String

Yes

Content-Type

Header

application/json

String

Yes

reminderId

Path

ID for the reminder to delete.

String

Yes

Request body example

The request has no body.

Response

A successful call returns HTTP/1.1 204 No Content. If an error occurs, the response includes a response body with the error information.

Response body example

The following example shows the response body for an error response.

{
  "type": "FORBIDDEN",
  "message": "The user does not have permission to perform this operation."
}

Response body properties

Parameter Description Type

type

Short description.

Enum

message

Detailed description of the result.

String

HTTP status codes

Status Type Message

400

INVALID_REMINDER_ID

The provided reminder ID is invalid.

400

DEVICE_NOT_REACHABLE

Device not reachable/offline.

401

UNAUTHORIZED

The request is missing a valid access token in the Authorization HTTP Header. The token might be malformed or have expired.

403

FORBIDDEN

The user doesn't have permission to perform this operation.

404

REMINDER_NOT_FOUND

Reminder doesn't exist.

429

MAX_RATE_EXCEEDED

The request was throttled

500

INTERNAL_SERVER_ERROR

Get all reminders on an endpoint

Gets all the scheduled reminders for a specified endpoint. There is a 250 reminder limit on a device per caller.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES

US, UK, FR, CA, IT, DE, ES

US

Request

To get the reminders for an endpoint, make a GET call and set recipient.id to the endpoint ID.

GET /v2/alerts/reminders?recipient.id=amzn1.alexa.endpoint.did.<endpointId>&recipient.type=Endpoint&owner=~caller

Request header example

GET /v2/alerts/reminders?recipient.id=amzn1.alexa.endpoint.did.{endpointId}&recipient.type=Endpoint&owner=~caller HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {Access Token}

Request header and query parameters

Parameter Located in Description Type Required

recipient.id

Query

Unique identifier for the recipient. This is an endpoint ID.

String

Yes

recipient.type

Query

Type of recipient.
Accepted values: Endpoint

String

Yes

owner

Query

Owner of the reminders to retrieve.
Accepted values: ~caller. This means that operation returns reminders created by the user calling the operation.

String

Yes

access_token

Header

LWA access token. For details, see Authentication.

String

Yes

Content-Type

Header

application/json

String

Yes

Request body example

The request has no body.

Response

Returns the reminders for the specified endpoint.

Response body example

{
  "results": [
    {
      "recipient": {
        "id": "amzn1.alexa.endpoint.did.1234",
        "type": "Endpoint"
      },
      "reminder": {
        "reminderId": "84d26afa...",
        "createdTime": "2024-06-24T20:59:12.772Z",
        "updatedTime": "2024-06-24T20:59:12.929Z",
        "trigger": {
          "type": "SCHEDULED_ABSOLUTE",
          "scheduledTime": "2024-06-24T18:00:00.000",
          "timeZoneId": "America/Denver",
          "offsetInSeconds": 0
        },
        "status": "ON",
        "alertInfo": {
          "spokenInfo": {
            "content": [
              {
                "locale": "en-US",
                "text": "Bingo starts at five p.m.",
                "ssml": "<speak>Bingo starts at five p.m.</speak>"
              }
            ]
          }
        },
        "version": "2"
      }
    },
    {
      "recipient": {
        "id": "amzn1.alexa.endpoint.did.1234",
        "type": "Endpoint"
      },
      "reminder": {
        "reminderId": "c85c15a9...",
        "createdTime": "2024-06-21T23:36:25.342Z",
        "updatedTime": "2024-06-24T03:29:53.945Z",
        "trigger": {
          "type": "SCHEDULED_ABSOLUTE",
          "scheduledTime": "2024-06-24T17:40:00.000",
          "timeZoneId": "America/Denver",
          "offsetInSeconds": 0,
          "recurrence": {
            "startDateTime": "2024-06-01T00:00:00.000-06:00",
            "endDateTime": "2024-09-30T00:00:00.000-06:00",
            "recurrenceRules": [
              "FREQ=DAILY;INTERVAL=1;BYHOUR=17;BYMINUTE=40"
            ]
          }
        },
        "status": "ON",
        "alertInfo": {
          "spokenInfo": {
            "content": [
              {
                "locale": "en-US",
                "text": "Take your medication every day after dinner",
                "ssml": "<speak>Take your medication every day after dinner</speak>"
              }
            ]
          }
        },
        "version": "3"
      }
    }
  ]
}

Response body properties

The operation returns an array of results (results[]). Each result in the array has the properties shown in the following table.

Property Description Type

recipient

Recipient for this reminder.

Object

recipient.type

The type of the recipient.
Possible values: Endpoint.

Enum

recipient.id

Unique identifier for the recipient. This is always an endpoint ID.

String

reminder

Contents of the reminder.

Object

reminder.reminderId

Unique ID of this reminder alert.

String

reminder.createdTime

Created time of this reminder in ISO 8601 format.

String

reminder.updatedTime

Last updated time of this reminder in ISO 8601 format.

String

reminder.status

Indicates the current status of the reminder.
Possible values:

  • ON – This is an active reminder that will play in the future.
  • COMPLETED – The reminder has already triggered. Completed reminders are deleted after three days.

Enum

reminder.version

Version of this reminder alert. Version numbers are incremented upon update.

String

reminder.trigger

Contains information about the trigger for the reminder.

Object

reminder.trigger.type

Indicates type of trigger.
Possible values: SCHEDULED_ABSOLUTE or SCHEDULED_RELATIVE.

Enum

reminder.trigger.offsetInSeconds

Applies when the trigger.type is to SCHEDULED_RELATIVE. Specifies the number of seconds after requestTime to play the reminder.

Integer

reminder.trigger.scheduledTime

Trigger date and time of the reminder in ISO 8601 format.

  • For a relative reminder, this field contains the calculated trigger time based on the requestTime and offsetInSeconds provided when creating the reminder.
  • For a recurring reminder, this field contains either the next trigger date and time, or the most recent trigger date and time, based on the recurrence rules.

    There is an expected delay between when an instance of the recurring reminder is delivered and when the device schedules the next instance. During this delay, the scheduledTime returns the most recent trigger date and time and not the future time. For longer recurrence intervals, the device schedules the next instance in three to four hours. For shorter intervals, the scheduling occurs in under an hour.

String

reminder.trigger.timeZoneId

A string containing the ID of the time zone. For details about time zones, see Time zones for absolute times.

Enum

reminder.trigger.recurrence

Contains recurrence information for reminders that repeat at regular intervals.

Object

reminder.trigger.recurrence.startDateTime

The start of the recurrence pattern. Includes both the date and time.

String

reminder.trigger.recurrence.endDateTime

The end of the recurrence pattern. Returns an empty string for reminders that don't have a defined end time and therefore repeat indefinitely.

String

reminder.trigger.recurrence.recurrenceRules

The recurrence pattern for a repeating reminder, in the RRULE format.

String

reminder.alertInfo

Contains information about the reminder.

Object

reminder.alertInfo.spokenInfo

Contains information about the spoken content in the reminder.

Object

reminder.alertInfo.spokenInfo.content

Contains the content of the reminder. There can be multiple entries because the caller might have specified different reminders for different locales.

Array of objects

reminder.alertInfo.spokenInfo.content.locale

Locale for the reminder content.

String

reminder.alertInfo.spokenInfo.content.text

Default text used for display and spoken content.

String

reminder.alertInfo.spokenInfo.content.ssml

Text used for spoken content, in Speech Synthesis Markup Language (SSML) format.

String

HTTP status codes

Status Type Message

400

INVALID_REMINDER_ID

The provided reminder ID is invalid.

400

INVALID_RECIPIENT_TYPE

Th provided recipient type is invalid

401

UNAUTHORIZED

The request is missing a valid access token in the Authorization HTTP Header. The token might be malformed or have expired.

403

FORBIDDEN

The user doesn't have permission to perform this operation.

429

MAX_RATE_EXCEEDED

The request was throttled

500

INTERNAL_SERVER_ERROR


Was this page helpful?

Last updated: Jul 19, 2024