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.
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:
|
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:
|
|
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:
|
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:
|
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 |
Related topics
- 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.