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

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

Field Type Description
duration ISO-8601 representation of duration Required. Duration of the timer. Must be less than or equal to 2 hours. For example, If the duration is set to 90 minutes, the timer will go off in 90 minutes from the time of creation.
timerLabel String Optional. Name of the timer, with a limit of 256 characters.
creationBehavior Object Object that defines the timer creation behavior.
creationBehavior.displayExperience Object Object that defines whether timer creation is visible on an Alexa-enabled screen device.
creationBehavior.displayExperience.visibility String One of: VISIBLE | HIDDEN. Default is HIDDEN. If set to VISIBLE, the native Timer GUI is displayed for 8 seconds upon timer creation, if the user has an Alexa-enabled screen device.
triggeringBehavior Object Object that defines the triggering behavior for the timer.
triggeringBehavior.operation Object Object that describes the operation of the timer.
triggeringBehavior.operation.typeString One of: NOTIFY_ONLY | ANNOUNCE | LAUNCH_TASK
triggeringBehavior.notificationConfig Object Object that defines the notification configuration.
triggeringBehavior.notificationConfig.playAudible Boolean Whether the timer is audible. Can be true or false for ANNOUNCE and LAUNCH_TASK. Can only be true for NOTIFY_ONLY

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
    }
  }
}
Field Type Description
operation.textToAnnounce Object Object that contains the text and locale information for the timer.
operation.textToAnnounce.text String Text that Alexa speaks when the timer is triggered. Doesn't support SSML.

Note: Alexa appends the following text to beginning of the announcement. “From <skillname>”
operation.textToAnnounce.locale String Any locale that Alexa supports. Limit of 1 locale.

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
      }
    }
  }
}
Field Type Description
operation.textToConfirm Object Object that contains confirmation text and locale. Doesn't support SSML.
operation.textToConfirm.locale String Any locale that Alexa supports. Limit of 1 locale.
operation.textToConfirm.text String Text that Alexa speaks when the user is prompted to connect to another skill to complete a task. Doesn't support SSML.

{continueWithSkillName} is mandatory somewhere. This is replaced with "continue with <skill name>".

The task object must also be part of the request.

Field Type Description
task.name String Name of the task.
task.version String Version of the task.
task.input Object Optional. Object that contains task information. The skill developer includes customized task information in this object.

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"
}
Field Format/Type Description
id string Unique id of the timer. Format as opaque string.
status enum

Timer status may be:

  • ON - timer is active and will ring at triggerTime, or started ringing already, if triggerTime < now()
  • OFF - timer is not active and will not ever ring in future
  • PAUSED - timer was ON, but then was paused. This timer may be resumed, which will change its status to ON.
duration ISO-8601 representation of duration Duration of the timer
triggerTime ISO-8601 representation of a specified time Point in time when the timer will start ringing
timerLabel string Timer label, may be used by the user to reference timer
createdTime ISO-8601 representation of a specified time Point in time when the timer was created
updatedTime ISO-8601 representation of a specified time Point in time when the timer was last updated(paused, resumed or stopped). Otherwise the same as createdTime.
remainingTimeWhenPaused ISO-8601 representation of duration Duration remaining when timer was last paused. Only applicable to timers that have been paused.

Error codes for general validation

HTTP Status CodeDescriptionDetails
400 Bad RequestError in request format Any input validation error. Message contains detailed error description.
401 UnauthorizedRequest is not authorizedToken invalid or expired.
500 Internal Server Error Timer creation failed. One of various possible service-side issues

Error codes for parameter validation

HTTP Status Code Code Message
400 INVALID_DURATION Timers with duration of more than 2 hours are not supported.
INVALID_TIMER_LABEL Timer label is invalid, or timer label exceeded maximum length of 256 characters.
INVALID_SCHEMA_FORMAT One of:
  • Request timer duration format incorrect
  • LAUNCH_TASK operation must include custom task
  • NOTIFY_ONLY or ANNOUNCE doesn't support any format of custom tasks.
  • playAudible can have a value of true or false. Must be true if duration is longer than 30 minutes. LAUNCH_TASK timer.
TEXT_TOO_LONG Text in ANNOUNCE or text in confirmation or custom task name exceeds the maximum size of 2 KB.
OPERATION_NOT_SUPPORTED Operation only supports NOTIFY_ONLY, ANNOUNCE, or LAUNCH_TASK.
401 UNAUTHORIZED Token is valid, but does not have appropriate permissions.
403 MAX_TIMERS_EXCEEDED Maximum limit (10) of timers on the device reached.
500 INTERNAL_SERVER_ERROR Unexpected server-side failure.

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.

Field Parameter Type Description
id string Required. Unique id of the timer.

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"
Field Format/Type Description
id UUID unique id of the timer
status Enum

Timer status may be:

  • ON - timer is active and will ring at triggerTime, or started ringing already, if triggerTime < now()
  • OFF - timer is not active and will not ever ring in future
  • PAUSED - timer was ON, but then was paused. This timer may be resumed, which will change its status to ON.
duration ISO-8601 representation of duration Duration of the timer
triggerTime ISO-8601 representation of a specified time Point in time when the timer will start ringing
timerLabel string Timer label, may be used by the user to reference timer
createdTime ISO-8601 representation of a specified time Point in time when the timer was created
updatedTime ISO-8601 representation of a specified time Point in time when the timer was last updated(paused, resumed or stopped). Otherwise the same as createdTime.
remainingTimeWhenPaused ISO-8601 representation of duration Duration remaining when timer was last paused.

Error codes

Http Status CodeDescriptionDetails
400 Bad RequestError in request format Any input validation error. Message contains detailed error description.
401 UnauthorizedRequest is not authorizedToken invalid or expired.
404 Not Found Object not foundNo such timer exists.
500 Internal Server Error Timer read failed. One of various possible service-side issues

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
}
Field Format/Type Description
timers Array Array of timer objects
timers.id UUID Unique id of the timer
timers.status enum

Timer status may be:

  • ON – Timer is active and will ring at triggerTime, or started ringing already, if triggerTime < now()
  • OFF – timer is not active and will not ever ring in future
  • PAUSED – timer was ON, but then was paused. This timer may be resumed, which will change its status to ON.
timers.duration ISO-8601 duration Duration of the timer
timers.triggerTime ISO-8601 representation of a specified time Point in time when the timer will start ringing.
timers.timerLabel string Timer label, may be used by the user to reference timer.
timers.createdTime ISO-8601 representation of a specified time Point in time when the timer was created.
timers.updatedTime ISO-8601 representation of a specified time Point in time when the timer was last updated (paused, resumed or stopped). Otherwise the same as createdTime.
timers.remainingTimeWhenPaused ISO-8601 duration Duration remaining when timer was last paused.
totalCount integer Number of timer objects returned.
nextToken null null is the only supported value.

Error codes

Http Status CodeDescriptionDetails
400 Bad RequestError in request format. Any input validation error. Message contains detailed error description.
401 UnauthorizedRequest is not authorizedToken invalid or expired.
500 Internal Server Error Timer read failed. One of various possible service-side issues.

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.

Field Parameter Type Description
id string Required. Unique id of the timer.

Response

HTTP/1.1 200 OK

No response body

Error codes

Http Status CodeDescriptionDetails
400 Bad RequestError in request format. Any input validation error. Message contains detailed error description.
401 UnauthorizedRequest is not authorizedToken invalid or expired.
404 Not FoundObject not foundNo such timer exists.
500 Internal Server Error Timer delete failed. One of various possible service-side issues.

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

Http Status CodeDescriptionDetails
400 Bad RequestError in request format. Any input validation error. Message contains detailed error description.
401 UnauthorizedRequest is not authorized.Token invalid or expired.
500 Internal Server Error. Timers delete failed. One of various possible service-side issues.

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.

Field Parameter Type Description
id string Required. Unique id of the timer.

Response

HTTP/1.1 200 OK

No response body

Error codes

Http Status CodeDescriptionDetails
400 Bad RequestError in request format Any input validation error. Message contains detailed error description.
401 UnauthorizedRequest is not authorizedToken invalid or expired.
404 Not FoundObject not foundNo such timer exists.
500 Internal Server Error Operation failed. One of various possible service-side issues.

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.

Field Parameter Type Description
id string Required. Unique id of the timer.

Response

HTTP/1.1 200 OK

No response body.

Error codes

Http Status CodeDescriptionDetails
400 Bad RequestError in request format Any input validation error. Message contains detailed error description.
401 UnauthorizedRequest is not authorized.Token invalid or expired.
404 Not FoundObject not found.No such timer exists.
500 Internal Server Error Operation failed. One of various possible service-side issues.

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

HTTP Status CodeEnumMessageAPI
400 INVALID_DURATION_FORMATRequest duration format incorrect.create
INVALID_TIMER_ID Timer ID is null or blank.get, resume, pause, delete
MAX_DURATION_EXCEEDED Timers with a duration of more than 2 hours are not supported.create
TIMER_LABEL_TOO_LONG Timer label exceeded maximum length, which is 256 characters.create
INVALID_TIMER_LABEL Timer label is invalid.create
TIMER_ALREADY_PAUSED Tried to pause timer which is in PAUSED state already. pause
TIMER_IS_NOT_PAUSED Tried to resume timer which is not in PAUSED state. resume
401 UNAUTHORIZED Authorization/
authentication failure due to: missing token, invalid token or missing permissions 		authorization. Also when skillId/deviceId from accessToken is null.
403 MAX_TIMERS_EXCEEDED Maximum limit of timers on the device reached (25).create
404 TIMER_NOT_FOUND Timer does not exist.get, resume, pause, delete.
500 INTERNAL_SERVER_ERROR Unexpected server side failureall APIs
504 DEVICE_NOT_REACHABLE Device not reachable/offline. all APIs