Understand Alexa Timers

With the Alexa Timers API – which consists of a set of REST APIs – you can add timer capabilities to your skill. A skill requires explicit customer permission to create timers, and customers can only manage timers that the skill itself has created for that customer. For more information, see Alexa Timers API Reference and Alexa Timers Guidelines.

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, thus ensuring that the user experience with the skill is not interrupted.

Obtain user permissions

Before your skill can create timers, you must obtain 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 is time for a timer to go off, Alexa proceeds with the timer regardless of whatever interaction the user may be having with Alexa at that moment. This may be disruptive if the user is not 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, which is acquired 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 30min 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 is 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 is 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 information, see Handling Requests Sent by Alexa.