Alexa Timers API Reference

Use the Alexa Timers API so that your skill can create and manage timers for your users. This reference document describes the available operations for the Alexa Timers API.

For more details on how timers operate, see Understand Alexa Timers and Alexa Timers Best Practices.

• Alexa Timers API endpoint and authorization
• In-session and out of session behavior for Alexa Timers API
• Create a timer
• Read the specified timer
• Read all timers for a specified customerId
• Cancel a specified timer
• Cancel all timers
• Pause a specified timer
• Resume a specified timer
• How time zones work for timers
• Comprehensive list of error messages
• Subscribe to timer events
  • Timer events in JSON format

Alexa Timers API endpoint and authorization

You get the API endpoint from the apiEndpoint value in the context object of the incoming request.

• North America – https://api.amazonalexa.com
• Europe – https://api.eu.amazonalexa.com
• Far East – https://api.fe.amazonalexa.com

Each API request must have an Authorization header. For this value, use the access token retrieved from Login with Amazon.

The id used in some operations refers to the id of the timer. This id automatically generates when the timer gets created.

In-session and out of session behavior for Alexa Timers API

You create (POST) timers with an in-session access token – don't use an out-of-session token.

GET, UPDATE, and DELETE operations work with both in-session and out-of-session access tokens. For more details about using out-of-session access tokens, see Out of session interaction.

Create a timer

A skill invokes this API to create a new timer for the current skill. Your skill can trigger a timer to provide a simple notification, to provide an announcement, or to launch a task.

• The trigger time calculates based on the moment that the request is received.
• Timers with different labels, and timers without labels, can have the same duration.
• If you use timer labels, they must be unique. Otherwise, a 400 error returns.

Request

POST /v1/alerts/timers

Header of the request

Authorization: Bearer <<apiAccessToken>>
Content-Type: application/json

Example request body

{
  "duration": "PT10M",
  "timerLabel": "exercise",
  "creationBehavior": {
     "displayExperience": {
         "visibility": "VISIBLE" | "HIDDEN"
    }
 },
  "triggeringBehavior": {
    "operation": {
      "type": "NOTIFY_ONLY" | "ANNOUNCE" | "LAUNCH_TASK",
	  ...<content varies by type of timer>...	  
    },
    "notificationConfig": {
      "playAudible": true
    }
  }
}

Parameters

Create a timer: operation NOTIFY_ONLY

A NOTIFY_ONLY timer only sounds a tone – Alexa doesn't speak, read out any announcements or launch any new tasks. This timer can only have a playAudible value of true.

When playAudible is true, the following behavior occurs:

1. The timer elapses.
2. The user must say "Alexa, stop" to stop the timer. Otherwise, the timer rings for the full length of time.

Example of operation NOTIFY_ONLY timer

 "operation": {
     "type" : "NOTIFY_ONLY"
 }

Example request body for operation NOTIFY_ONLY timer

{
  "duration": "PT10M",
  "timerLabel": "exercise",
  "creationBehavior": {
     "displayExperience": {
         "visibility": "HIDDEN"
    }
 },
  "triggeringBehavior": {
    "operation": {
      "type": "NOTIFY_ONLY"
    },
    "notificationConfig": {
      "playAudible": true
    }
  }
}

Create a timer: operation ANNOUNCE

An ANNOUNCE timer includes text that Alexa speaks after a timer triggers and when the user says "stop" or the timer stops ringing. This timer can be part of an instructional skill workflow.

If playAudible is true, the following behavior occurs:

1. The timer rings.
2. The user says "stop".
3. An announcement reads after the user says "stop".

If playAudible is false, the following behavior occurs:

• The timer elapses and an announcement starts immediately.

Example of operation ANNOUNCE timer

 "operation": {
     "type" : "ANNOUNCE",
     "textToAnnounce": [{
         "locale": "en-US",
         "text": "That's enough stretching, start to run"
    }]
 }

Example request body for operation ANNOUNCE timer

{
  "duration": "PT10M",
  "timerLabel": "exercise",
  "creationBehavior": {
     "displayExperience": {
         "visibility": "HIDDEN"
    }
 },
  "triggeringBehavior": {
    "operation": {
      "type": "ANNOUNCE",
      "textToAnnounce": [
        {
          "locale": "en-US",
          "text": "That's enough stretching, start to run"
        }
      ]
    },
    "notificationConfig": {
      "playAudible": true
    }
  }
}

Create a timer: operation LAUNCH_TASK

Use the LAUNCH_TASK operation in conjunction with Skill Connections. You will create your own task.

If playAudible is true, the following behavior occurs:

1. The timer rings.
2. The user says "stop".
3. The confirmation dialog plays, which the user either confirms or denies.
4. If the user acknowledges the confirmation dialog, the skill launches.

If playAudible is false, the following behavior occurs:

1. The timer elapses.
2. The confirmation dialog plays, which the user either confirms or denies.
3. If the user acknowledges the confirmation dialog, the skill launches.

Example of operation LAUNCH_TASK timer

 "operation": {
     "type" : "LAUNCH_TASK",
     "textToConfirm": [{
         "locale": "en-US",
         "text": "That’s enough stretching. Would you like to {continueWithSkillName} to start your run?"} [],
		 {
     }
	 }],
     "task" : {
         "name" : "exercise",
         "version" : "1",
         "input" : {
               ...
			   <customized input by developer>
			   ...
        }
    }
 }

Example request body for operation LAUNCH_TASK timer

{
  "duration": "PT30S",
  "timerLabel": "print",
  "creationBehavior": {
     "displayExperience": {
         "visibility": "HIDDEN"
    }
 },
  "triggeringBehavior": {
    "operation": {
      "type": "LAUNCH_TASK",
      "task": {
        "name": "<customTask.NAME>",
        "version": "<customTask.VERSION>",
        "input": {
          "type": "PrintImageRequest",
          "version": "1",
          "title": "Beautiful scenic image",
          "url": "http://www.example.com/beautiful-scenic-image.jpg",
          "imageType": "JPEG"
        }
      },
      "textToConfirm": [
        {
          "locale": "en-US",
          "text": "Your print timer is up! Would you like to pass focus back skill {continueWithSkillName}"
        }
      ],
      "notificationConfig": {
        "playAudible": true
      }
    }
  }
}

The task object must also be part of the request.

Response

HTTP/1.1 200 OK

Example response body

{
  "id": "opaque, unique string",
  "status": "PAUSED",
  "duration": "PT10M",
  "triggerTime": "2019-09-12T19:10:00.083Z",
  "timerLabel": "chicken",
  "createdTime": "2019-09-12T19:00:00.083Z",
  "updatedTime": "2019-09-12T19:04:35.083Z",
  "remainingTimeWhenPaused": "PT5M25S"
}

Error codes for general validation

Error codes for parameter validation

Read the specified timer

This API is invoked to get a specific timer object as specified by its id value. A skill can read only those timers that it has created.

Request

GET /v1/alerts/timers/{id}

Header of the request

Authorization: Bearer <<apiAccessToken>>
Content-Type: application/json

No request body.

Response

HTTP/1.1 200 OK

Example response body for a timer with no label

{
  "id": "a3aac326-c504-458b-8520-15fd048f086a",
  "status": "ON",
  "duration": "PT10M",
  "triggerTime": "2019-12-03T10:25:30Z",
  "createdTime": "2019-12-03T10:15:30Z",
  "updatedTime": "2019-12-03T10:15:30Z"
}  

If the timer that is returned has previously been paused, the remainingTimeWhenPaused property is also returned in the response:

  "remainingTimeWhenPaused": "PT3M3S"

Error codes

Read all timers for a specified customerId

Get timers for a specified customer ID. Those timers that are created by the skill on any devices are returned, sorted in order from the timer with the shortest duration to the longest duration. The listed timers are displayed on a single page, and pagination is not currently supported.

If no timers are found, then an empty list with a totalCount of 0 is returned.

Request

GET /v1/alerts/timers

Header of the request

Authorization: Bearer <<apiAccessToken>>
Content-Type: application/json

No request body.

Response

HTTP/1.1 200 OK

Example response body

In this example, two timers are returned, one of which is paused.

{
  "timers": [
    {
      "id": "a3aac326-c504-458b-8520-15fd048f086a",
      "status": "ON",
      "duration": "PT10M",
      "triggerTime": "2019-12-03T10:25:30Z",
      "createdTime": "2019-12-03T10:15:30Z",
      "updatedTime": "2019-12-03T10:15:30Z",
    },
    {
      "id": "a3aac326-c504-458b-8520-15fd048f086a",
      "status": "PAUSED",
      "duration": "PT5M",
      "timerLabel": "Pizza",
      "createdTime": "2019-12-03T10:15:30Z",
      "updatedTime": "2019-12-03T10:12:03Z",
      "remainingTimeWhenPaused": "PT3M3S"
    }
  ],
  "totalCount": 2,
  "nextToken": null
}

Error codes

Cancel a specified timer

This API is invoked to cancel a specific timer for the current device.

Request

DELETE /v1/alerts/timers/{id}

Header of the request

Authorization: Bearer <<apiAccessToken>>
Content-Type: application/json

No request body.

Response

HTTP/1.1 200 OK

No response body

Error codes

Cancel all timers

Delete all timers. All timers created by the skill on any devices are deleted.

Request

DELETE /v1/alerts/timers

Header of the request

Authorization: Bearer <<apiAccessToken>>
Content-Type: application/json

No request body.

Response

HTTP/1.1 200 OK

No response body.

Error codes

Pause a specified timer

Invoke this API to pause a timer.

You can pause a timer that is scheduled, but has not started yet. The timer's remaining time is frozen and saved. For example, if you pause a timer that is due to go off in 45 minutes, then the timer will go off 45 minutes from when you resume the timer.

Request

POST /v1/alerts/timers/{id}/pause

Header of the request

Authorization: << apiAccessToken>>
Content-Type: application/json

No request body.

Response

HTTP/1.1 200 OK

No response body

Error codes

Resume a specified timer

Invoke this API to resume a previously paused timer. The timer will then run for the remaining time after resuming, unless it is otherwise paused or stopped.

Request

POST /v1/alerts/timers/{id}/resume

Header of the request

Authorization: << apiAccessToken>>
Content-Type: application/json

No request body.

Response

HTTP/1.1 200 OK

No response body.

Error codes

How time zones work for timers

The triggerTime, createdTime, and updatedTime fields all use the UTC (Universal Time Coordinated) time zone. Alexa makes the necessary calculations so that the timer rings at the correct time for the user.

Comprehensive list of error messages

Subscribe to timer events

By subscribing to timer events, your skill can be notified of these events without calling the Alexa Timer API. Your skill can use account linking to integrate with an external app, and use notifications of these events to make changes in the app, such as by deleting or modifying the timers in the app.

Any action that a skill takes as the result of a timer event should consider the timestamp of the event, as notifications of events might arrive out of order. For example, if a timer is updated twice, and the earlier update event arrives after the second update event, then the earlier update should be disregarded.

Alexa attempts to redeliver events if the skill service doesn't send an acknowledgment in response. The skill service can't retrieve past events from Alexa, but must rely on the events being delivered.

For more details on subscribing to timer events, see Skill events in Alexa skills.

Timer events in JSON format

Your skill can subscribe to timer events. You set this process up by configuring your skill.json manifest file. For more details on this process, see Use Events in Your Skill Service.