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
- Your skill creates a timer for cooking chicken that's set for five minutes from now.
- If there is no interruption, after five minutes, the timer starts ringing.
- 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").
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
- Your skill creates a timer that's set for five minutes from now.
- After one minute, the user says "Alexa, pause," or the equivalent, or the skill calls the Pause API method.
- The skill pauses the timer.
- The timer remains in a paused state until the user says, "Alexa, resume," or the skill calls the Resume API method.
- After resuming the timer, the skill waits another four minutes, and then the timer starts ringing.
- 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.
- 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
- Implement timer capabilities in your skill service code.
- 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.
- 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
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.
The following example shows the access token in an
Authorization header in the format: Bearer
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.
- For more details about following best practices when creating timers, see Alexa Timers Best Practices.
- For more details about using timers with voice permissions, see Set Up Voice Permissions for Timers.
- For more details about using the timers API, see Timers REST API Reference.
Was this page helpful?
Last updated: Nov 29, 2023