Best Practices for Timers

Use the following best practices when you create skill timers with the Timers REST API.

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:

  • If your timer includes a label, it must be unique.
  • You can create a maximum of 10 timers, including both skill and personal timers.
  • The maximum timer duration of a timer is two hours. Your skill acan't create a timer that starts more than two hours from the time of its creation.

Timer usage examples

In general, any skill that has multiple steps or involves tracking time might benefit from the use of timers – note that timers are conceptually different then reminders that you create using the Reminders API.

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

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

The following examples demonstrate how you might use timers in 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 the user replies "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 the user answers "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 the user answers "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 don't 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 two 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 make sure your users have a good experience using timers.

  • Let the user know if there is a failure to set the timer.
  • Inform the user if the skill fails to run 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 runs the API only if you are certain that the action should run.
  • 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 isn't 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>."
  • Make sure that your skill meets the requirements of the skill submission checklist.
Was this page helpful?

Last updated: Nov 29, 2023