Understand Alexa Timers

You use the Alexa Timers API to add timers to your skills. This page provides a brief overview of how timers work. For more details about how to use timers, see Timers REST API Reference and Best Practices for Timers.

Include timers in your skill

If you use the Alexa Timers API, you can integrate timers directly into your skill so that the user doesn't have to go outside the skill to set a timer. This behavior can help create a better user experience because someone using your skill isn't interrupted from what they're doing.

Obtain user permissions

Before your skill can create timers, you must obtain explicit user permission to do so. The Alexa service provides permission to use timers on a per-skill basis. If the user has not granted permission to the skill to create timers, make sure that your skill informs the user about how to grant permissions, and that the skill sends a home card providing a link to the skill permissions page in the Alexa app.

If a skill has created a timer, and it's time for a timer to go off, Alexa proceeds with the timer regardless of type of interaction the user is having with Alexa at that moment. This might be disruptive if the user isn't expecting this timer. To protect users from unexpected interruptions, a skill must acquire these two sets of permissions to create a timer:

  • A Global Timers Read/Write permission. You acquire this permission during skill enablement.
  • Explicit user permission for the extended experience enabled by the timer. Obtain explicit permission as part of the dialog your skill has with the user. For example, you can ask the user, "Would you like to start your 30 minute workout"?

Timer workflow examples

The following examples show the processes that occur after your skill user agrees to have a timer set, the timer rings, and then the user says either "stop" or "pause."

Stop timer workflow

  1. Your skill creates a timer for cooking chicken that's set for five minutes from now.
  2. If there is no interruption, after five minutes, the timer starts ringing.
  3. If the timer is labeled, then, in addition to ringing, Alexa periodically says "Your chicken timer is done" (if the timer has the label "chicken").

  4. The timer then continues to ring until one of these two actions occurs:

    • The user says "Alexa, stop," or the equivalent.
    • 60 minutes passes without a response. The timer stops ringing.

Pause timer workflow

  1. Your skill creates a timer that's set for five minutes from now.
  2. After one minute, the user says "Alexa, pause," or the equivalent, or the skill calls the Pause API method.
  3. The skill pauses the timer.
  4. The timer remains in a paused state until the user says, "Alexa, resume," or the skill calls the Resume API method.
  5. After resuming the timer, the skill waits another four minutes, and then the timer starts ringing.
  6. The timer continues to ring for an hour, unless stopped as described under Stop timer workflow.

Add timers to your skill

If you have an existing Alexa custom skill, or are building a new custom skill, you can integrate with Alexa timers by following these steps.

  1. Set up your skill so that it has the capability to request user permissions to create timers. To do this in the Amazon developer console, go to the Build page for your skill, and then scroll down and select the Permissions section on the lower left. Turn on the switch for Timers. If you are using SMAPI to build your skill, edit the skill manifest directly to add alexa::alerts:timers:skill:readwrite to the permissions.name array.
  2. Implement timer capabilities in your skill service code.
  3. Make sure that your skill requests Timers permission from the user. Use the APIs to read and update the timers. A skill can only access timers created by that skill.
  4. Your skill user should receive a card in the Alexa app that indicates that the timer has been delivered.

Manage permissions with an apiAccessToken

When your skill uses the Alexa Timers API to create a timer, your skill must provide an in-session ID where the user has explicitly granted permission. If the Alexa Timers API determines that a skill has violated the permission policy, the API revokes the timers access. Your skill can't use an out-of-session token to create a timer, but your skill can use the token to edit or delete a timer.

If your skill doesn't have explicit user permission, such as the first time the user invokes the skill, it must obtain user permission by sending a permissions card to the user. For more information, see Permissions card for requesting user consent. The scope for timers is alexa::alerts:timers:skill:readwrite.

Each request sent to your skill includes an API access token (apiAccessToken) that encapsulates the permissions granted to your skill. Your skill service needs to retrieve this token for use when you call the API to create a timer. In the following example, apiAccessToken is nested in the System object, which is nested in the context object. For information about the full body of the request, see Request Format.

{
  "context": {
    "System": {
      "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.amazonalexa.com",
      "device": {
        "deviceId": "string-identifying-the-device",
        "supportedInterfaces": {}
      },
      "application": {
        "applicationId": "string"
      },
      "user": {}
    }
  }
}

The following example shows the access token in an Authorization header in the format: Bearer ACCESS_TOKEN, where ACCESS_TOKEN is the value of the apiAccessToken field from the Alexa request message.

Authorization: Bearer AxThk...6fnLok

The following example shows the access token in Node.js.

accessToken = this.event.context.System.apiAccessToken

For more about managing permissions with an apiAccessToken, see Handling Requests Sent by Alexa.

Was this page helpful?

Last updated: Nov 29, 2023