Alexa Timers Best Practices

When you use the Alexa Timers API to create timers within your skill, adhere to the following best practices to make sure that your users have a good experience using the timers.

Make sure your timers relate to your skills purpose. For example, if your skill gives steps for a bread recipe, your skill might set a one-hour timer to let the dough rise. Don't use your skill to set timers for unrelated activities.

Understand timer states and valid transitions

A timer typically passes through multiple states. The following flow chart shows the possible states and the valid transitions between them. If your skill attempts an invalid transition, your skill get an error response. For example, your skill can't resume a stopped timer, although your skill can resume a paused timer.

Flow chart for timer states

Observe timer constraints

For each skill that supports the creation of timers, make sure that you adhere to the following constraints:

  • Unique label for each timer, if a label is provided.
  • Maximum of 10 timers, including both skill and personal timers.
  • Maximum timer duration of 2 hours. Your skill can't create a timer that starts more than 2 hours from the time of its creation.

Timer usage examples

You might find that timers are useful in skill categories such as the following:

  • Cooking
  • Chores
  • Games
  • Learning
  • Exercise
  • Crafting
  • Cosmetics

In general, any skill that has multiple steps or involves tracking time might benefit from the use of timers – these are different then the Reminders API, which are prearranged messages that Alexa speaks to the customer at a specific time. The following examples show how to use timers for a cooking skill, a meditation skill, and a laundry skill.

If you create a step-by-step cookie baking skill, there are some natural points at which your skill could create a timer. In this example, your recipe dictates how long each step should take and your skill doesn't ask the user for the duration.

Ask the user if they would like to set a timer for their cookies. If yes, ask for permission to create a two timers, with the following durations.

  • One 12 minute ANNOUNCE timer to inform them that their cookies finished baking and to remove them from the oven.
  • One 14 minute NOTIFY_ONLY timer to inform them that their cookies are ready to eat. This timer activates after the user stops the previous 12 minute timer.

Meditation timer example

If you create a meditation skill, you can use timers to track when the meditation should stop. In this example, you program a set of timers that follows a specific pattern and don't ask the user for input.

Ask the user if they would like to begin their 15 minute meditation session.

  • If yes, ask for permission to create a 15 minute ANNOUNCE timer that provides a message when the meditation ends.
  • You can run this timer alongside playing audio that softens and then ends at 15-minutes.

Laundry timer example

If you create a laundry skill, you can use timers to help complete the task. In this example, you don't know how long certain steps should take, but you ask the user and set the timer durations accordingly.

  • Ask the user if any clothing item requires a pre-soak treatment, and how long the pre-soak period should be. If yes, ask for permission to create a "pre-soak" timer for a duration the user chooses, such 30 minutes.
  • Ask the user how long the washing machine takes to do a load of laundry. Ask the user for permission to create a "washing" timer for that duration of time.
  • Ask the user how long they want to wait for the dryer. Ask the user for permission to create a "drying" timer for that duration of time.

Timer labels

If you choose to include a timerLabel for a timer, follow these guidelines.

  • Indicate the purpose of the timer in the label name.
  • Use a short label, no longer than three words.
  • Use discretion when setting the label, and do not include sensitive information in the label.
  • Make sure that the label is in the user's device language, unless another language is specifically required.
  • Don't include unsolicited content.

Timer duration

In general, you want to avoid surprising or annoying the user with timers in your skill. Follow these guidelines:

  • Make the timer duration as short as possible; it can’t exceed 2 hours.
  • Confirm the trigger time with the user before triggering a timer between 10 PM and 6 AM.
  • Use the AMAZON.DURATION slot type to convert words that indicate durations into a numeric duration.

Best practices for coding timers in your skill

Follow these best practices to ensure a good experience with timers for your users.

  • Let the user know if there is a failure to set the timer.
  • Inform the user if the skill fails to execute an operation.
  • Check the constraints in advance and fail gracefully if necessary.
  • Make sure the error is clear if there is an invalid state change.
  • Make sure the skill fails gracefully and communicates clearly to the user if there is a missing permission.
  • Make sure that the skill executes the API only if you are certain that the action should be executed.
  • Plan for the fact that you can't set an explicit trigger time setting. The API sets the timer based on the moment that the server processes the request.
  • Inform the user if the suggested label is not unique. This applies only if the user is choosing the timerLabel.
  • Inform the user of the total number of timers that they have. For example, "You now have three timers set for <skillname>."
  • Ensure that your skill meets the requirements of the skill submission checklist.
  • The Skill Simulator doesn't support Timers.