Vielen Dank für deinen Besuch. Diese Seite ist nur in Englisch verfügbar.

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"         
    }
}
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 reminder will ring (in seconds). integer
trigger.timeZonId 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 list of days within a week. Use standard two-letter abbreviations. 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 that will be 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": "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 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.

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 will attempt 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

The 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:

  • REMINDER_STARTED
  • REMINDER_CREATED
  • REMINDER_UPDATED
  • REMINDER_STATUS_CHANGED
  • REMINDER_DELETED

ReminderStarted

This event is generated when the Reminder started ringing. NotificationStarted event in the speechlet will generate this event. This allows skill to take actions on their end at trigger time

{
  "version": "1.0",                                 // Version, String
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"             // Skill id, String
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",      // Skill user id, String
        "accessToken": "<access_token>",          // Token to identify user in 3P
        "permissions": {
          "consentToken": "Atza|IgEB..."            // Token to call Reminder API
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"  // Endpoint to call Reminders API
    }
  },
  "request": {
    "type": "Reminders.ReminderStarted",
    "requestId": "913e4588-62f9-4d5b",              // String
    "timestamp": "2017-09-15T01:46:14Z",            // Timestamp of event, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "alertToken": "<alert-token-value>",      // Reminder that was ringing
    }
  },
  "session": {
    "attributes": {}
  }
}

ReminderCreated

This event is generated when a reminder is created in the Alexa system. It informs the skill that a reminder has been created. This event is not sent to the creator of the reminder.

{
  "version": "1.0",                                 // Version, String
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"             // Skill id, String
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",      // Skill user id, String
        "accessToken": "<access_token>",          // Token to identify user in 3P
        "permissions": {
          "consentToken": "Atza|IgEB..."            // Token to call Reminders API
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"  // Endpoint to call Reminders API
    }
  },
  "request": {
    "type": "Reminders.ReminderCreated",
    "requestId": "<requestId-value>",              // String
    "timestamp": "2017-09-15T01:46:14Z",            // Timestamp of event, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "alertToken": "<alert-token-value>",          // Reminder token that was created
    }
  },
  "session": {
    "attributes": {}
  }
}

ReminderDeleted

This event is generated when a reminder is deleted by the customer.

{
  "version": "1.0",                                 // Version, String
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"             // Skill id, String
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",      // Skill user id, String
        "accessToken": "<access_token>",          // Token to identify user in 3P
        "permissions": {
          "consentToken": "Atza|IgEB..."            // Token to call Reminders API
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"  // Endpoint to call Reminders API
    }
  },
  "request": {
    "type": "Reminders.ReminderDeleted",
    "requestId": "<requestId-value",              // String
    "timestamp": "2017-09-15T01:46:14Z",            // Timestamp of event, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "alertToken": "<alert-token-value>",      // alertToken that was deleted
    }
  },
  "session": {
    "attributes": {}
  }
}

ReminderUpdated

This event is generated when a reminder is updated, including when a reminder is cancelled, deferred, completed, paused, resumed, snoozed, turned on, has its trigger time updated, or has its label updated. No details are provided on the update, except for the current state of the reminder. To get further details on the update, the skill should use the Get a reminder to retrieve the details of the update.

{
  "version": "1.0",                                 // Version, String
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"             // Skill id, String
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",      // Skill user id, String
        "accessToken": "<access_token>",          // Token to identify user in 3P
        "permissions": {
          "consentToken": "Atza|IgEB..."            // Token to call API
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"  // Endpoint to call API
    }
  },
  "request": {
    "type": "Reminders.ReminderUpdated",
    "requestId": "913e4588-62f9-4d5b",              // String
    "timestamp": "2017-09-15T01:46:14Z",            // Timestamp of event, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "status": "DEFERRED"                          // describes the status of the Reminder
      "alertToken": "09d9d7df-05be-438c-veba",      // alertToken that was updated
    }
  },
  "session": {
    "attributes": {}
  }
}