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.

Important: The request body differs depending on the operation.type set.

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.type`	String	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:

The timer elapses.
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:

The timer rings.
The user says "stop."
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:

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

If playAudible is false, the following behavior occurs:

The timer elapses.
The confirmation dialog plays, which the user either confirms or denies.
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 Code	Description	Details
400 Bad Request	Error in request format	Any input validation error. Message contains detailed error description.
401 Unauthorized	Request is not authorized	Token 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 Code	Description	Details
400 Bad Request	Error in request format	Any input validation error. Message contains detailed error description.
401 Unauthorized	Request is not authorized	Token invalid or expired.
404 Not Found	Object not found	No 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 Code	Description	Details
400 Bad Request	Error in request format.	Any input validation error. Message contains detailed error description.
401 Unauthorized	Request is not authorized	Token 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 Code	Description	Details
400 Bad Request	Error in request format.	Any input validation error. Message contains detailed error description.
401 Unauthorized	Request is not authorized	Token invalid or expired.
404 Not Found	Object not found	No 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 Code	Description	Details
400 Bad Request	Error in request format.	Any input validation error. Message contains detailed error description.
401 Unauthorized	Request 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 Code	Description	Details
400 Bad Request	Error in request format	Any input validation error. Message contains detailed error description.
401 Unauthorized	Request is not authorized	Token invalid or expired.
404 Not Found	Object not found	No 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 Code	Description	Details
400 Bad Request	Error in request format	Any input validation error. Message contains detailed error description.
401 Unauthorized	Request is not authorized.	Token invalid or expired.
404 Not Found	Object 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 Code	Enum	Message	API
400	INVALID_DURATION_FORMAT	Request 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 failure	all APIs
504	DEVICE_NOT_REACHABLE	Device not reachable/offline.	all APIs

For conceptual information about timers, see Understand Alexa Timers.
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.

Alexa Timers API Reference

Alexa Timers API endpoint and authorization

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

Create a timer

Request

Create a timer: operation NOTIFY_ONLY

Create a timer: operation ANNOUNCE

Create a timer: operation LAUNCH_TASK

Response

Error codes for general validation

Error codes for parameter validation

Read the specified timer

Request

Response

Error codes

Read all timers for a specified customerId

Request

Response

Error codes

Cancel a specified timer

Request

Response

Error codes

Cancel all timers

Request

Response

Error codes

Pause a specified timer

Request

Response

Error codes

Resume a specified timer

Request

Response

Error codes

How time zones work for timers

Comprehensive list of error messages

Related topics