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.

See also: Alexa Reminders Overview and Alexa Reminders Guidelines.

Alexa Reminders API endpoint and authorization

The API's endpoint is https://api.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 will work with both in-session and out of session access tokens. See: Out of session interaction.

Create a reminder

This API is invoked 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" : "2016-09-22T19:04:00.672",
   "trigger": {
        "type" : "SCHEDULED_ABSOLUTE",
        "scheduledTime" : "2018-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" : "2018-09-22T19:04:00.672",
   "trigger": {
        "type" : "SCHEDULED_RELATIVE",
        "offsetInSeconds" : "7200",
   },
   "alertInfo": {
        "spokenInfo": {
            "content": [{
                "locale": "en-US", 
                "text": "walk the dog"
            }]
        }
    },
    "pushNotification" : {                            
         "status" : "ENABLED"         
    }
}
Parameter Type Description
requestTime string Valid ISO 8601 format. Describes the time when event actually occurred.
trigger object Contains information about the trigger for a reminder.
trigger.type enum Indicates type of trigger. SCHEDULED_ABSOLUTE or SCHEDULED_RELATIVE.
trigger.offsetInSeconds integer If trigger.type is set to SCHEDULED_RELATIVE, use this field to specify the time after which reminder will ring (in seconds).
trigger.timeZonId enum A string containing the ID of the time zone. See How time zones work.
trigger.recurrence object Contains information about recurrence information for the reminder.
trigger.recurrence.freq enum One of: WEEKLY, DAILY. Frequency type of the recurrence.
trigger.recurrence.byDay enum Specifies a list of days within a week. Use standard two-letter abbreviations.
alertInfo object Contains information about the alert.
alertInfo.spokenInfo object Contains information about the spoken content in the alert.
alertInfo.spokenInfo.content object Contains the content of the alert.
alertInfo.spokenInfo.content.locale enum Locale in which value is specified.
alertInfo.spokenInfo.content.text string Text that will be used for display and spoken purposes.
pushNotification object Contains information about the push notification.
pushNotification.status enum One of: ENABLED, DISABLED

Response

HTTP/1.1 200 OK

Body of the response

{
  "alertToken": "string",
  "createdTime": "2018-08-14T15:40:55.002Z",
  "updatedTime": "2018-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 reminder

This API is invoked to get a specified reminder for the current skill.

Request

GET /v1/alerts/reminders/{id}

Response

HTTP/1.1 200 OK

{
  "totalCount": "string",
  "alerts": [
    {
      "alertToken": "string",
      "createdTime": "2018-08-14T15:47:48.386Z",
      "updatedTime": "2018-08-14T15:47:48.386Z",
      "status": "ON",
      "trigger": {
        "type": "SCHEDULED_ABSOLUTE",
        "scheduledTime": "2018-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

This API is invoked by skills to get all reminders for the skill. This includes completed reminders, which will have a status of "OFF".

Request

GET /v1/alerts/reminders

Response

HTTP/1.1 200 OK

{
  "totalCount": "string",
  "alerts": [
    {
      "alertToken": "string",
      "createdTime": "2018-08-14T16:03:38.811Z",
      "updatedTime": "2018-08-14T16:03:38.811Z",
      "status": "ON",
      "trigger": {
        "type": "SCHEDULED_ABSOLUTE",
        "scheduledTime": "2018-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

This API is invoked to update a reminder for the current skill.

Request

PUT /v1/alerts/reminders/{id}

Body of the request

{
  "createdTime": "2018-08-14T15:53:12.919Z",
  "trigger": {
    "type": "SCHEDULED_ABSOLUTE",
    "scheduledTime": "2018-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": "2018-08-14T15:40:55.002Z",
  "updatedTime": "2018-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

This API is invoked 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 timezone. See this list of timezones 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 The 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" : "2018-06-01T19:00:00"

Relative calculations

Example: 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 timezone

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

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

This request will set the reminder in device's timezone at 7pm.

Case 2: Reminder in the timezone of the app

The skill provides the date+time and timezone 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" : "2018-06-01T19:00:00"
"timezoneId" : "America/New_York"

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

Error messages

Http Status CodeEnumMessage
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 Timezone 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.