Timers REST API Reference
Use the Timers REST API to create, pause, resume, and cancel timers in your skill. On timer expiration, Alexa can play an audible chime, provide an announcement, or launch a task.
For more details about timers, see Understand Alexa Timers.
API endpoint
Use one of the following endpoints, based on the context.System.apiEndpoint value in the request from Alexa:
- North America:
https://api.amazonalexa.com - Europe:
https://api.eu.amazonalexa.com - Far East:
https://api.fe.amazon.com
Authentication
For API requests from a skill session, include an authorization header whose value is the context.System.apiAccessToken retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest. You can create, pause, and resume a timer from a skill session only.
For out-of-session API requests from a website or app, include a Login with Amazon (LWA) access token in the authorization header. For more details about how to obtain the access token, see Send Messages to Your Skill.
Operations
The Timers API includes the following operations.
| Operation | HTTP method and URI |
|---|---|
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
|
Create timer
Create and set a new timer. You specify the timer duration and what happens when the timer expires. Alexa can play an audible chime, provide an announcement, or launch a task on timer expiration.
Request
To create a timer, you make a POST request to the timers resource.
Request path and header example
POST /v1/alerts/timers
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body notification examples
The following response shows a timer that plays a notification only.
The following response shows a timer that plays a notification and sends an announcement.
The following example shows a timer that plays a notification and launches a task.
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Length of time to run the timer. |
String |
Yes |
|
|
Name of the timer. The user can reference the timer by this name. |
String |
No |
|
|
Defines the behavior at timer creation. |
Object |
Yes |
|
|
Determines the timer behavior on an Alexa-enabled device with a screen. |
Object |
Yes |
|
|
Determines whether to display or hide the timer on an Alexa-enabled device with a screen. |
String |
Yes |
|
|
Defines what Alexa does when the timer expires. |
Object |
Yes |
|
|
Defines the operation to perform when the timer expires. |
Operation object |
Yes |
|
|
Defines whether to play a notification when the timer expires. |
Object |
Yes |
|
|
Indicates whether the timer expiration is audible. |
Boolean |
Yes |
Response
A successful response returns HTTP 200 OK, along with the timer details.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message. If you try to create more than the maximum allowed timers, Alexa returns HTTP 403 Forbidden with code= MAX_TIMERS_EXCEEDED.
Response body example
The following example shows a response.
{
"id": "timer.id",
"status": "PAUSED",
"duration": "PT10M",
"timerLabel": "exercise",
"triggerTime": "2019-09-12T19:10:00.083Z",
"createdTime": "2019-09-12T19:00:00.083Z",
"updatedTime": "2019-09-12T19:04:35.083Z",
"remainingTimeWhenPaused": "PT5M25S"
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Uniquely identifies the timer. |
String |
|
|
State of the timer.
|
String |
|
|
Length of the timer interval. |
String |
|
|
(Optional) Name of the timer. The user can reference the timer by this name. |
String |
|
|
Time when the timer expires and alerts the user. Note: Alexa calculates the trigger time based on the duration and the creation time in the customer's time zone.
|
String |
|
|
Time when the timer was created. |
String |
|
|
Time when the timer was last paused, resumed, or stopped. Otherwise, set to |
String |
|
|
(Optional) For paused timers, identifies the remaining time left on the timer. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the timer information. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25. |
|
|
Requested resource not found or the timer doesn't exist. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Cancel all timers
Cancel and delete all timers created by this skill for the customer on any Alexa-enabled device.
Request
To cancel timers, you make a DELETE request to the timers resource.
Request path and header example
DELETE /v1/alerts/timers
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The response has no body.
Response
A successful response returns HTTP 200 OK.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Successfully cancelled all timers for the customer for this skill. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25. |
|
|
Requested resource not found or the timer doesn't exist. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Cancel timer
Cancel and delete the specified timer.
Request
To cancel a timer, you make a DELETE request to the timers resource.
Request path and header example
DELETE /v1/alerts/timers/{id}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Timer ID. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The response has no body.
Response
A successful response returns HTTP 200 OK.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Successfully cancelled the specified timer. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25. |
|
|
Requested resource not found or the timer doesn't exist. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get timer
Get the specified timer created by this skill.
Request
To get a timer, you make a GET request to the timers resource.
Request path and header example
GET /v1/alerts/timers/{id}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Timer ID. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The response has no body.
Response
A successful response returns HTTP 200 OK, along with the timer details.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Uniquely identifies the timer. |
String |
|
|
State of the timer.
|
String |
|
|
Length of the timer interval. |
String |
|
|
(Optional) Name of the timer. The user can reference the timer by this name. |
String |
|
|
Time when the timer expires and alerts the user. Note: Alexa calculates the trigger time based on the duration and the creation time in the customer's time zone.
|
String |
|
|
Time when the timer was created. |
String |
|
|
Time when the timer was last paused, resumed, or stopped. Otherwise, set to |
String |
|
|
(Optional) For paused timers, identifies the remaining time left on the timer. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the timer information. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25. |
|
|
Requested resource not found or the timer doesn't exist. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List timers
Get all timers created by this skill for the customer on any Alexa-enabled device.
Request
To get timers, you make a GET request to the /v1/alerts/timers resource.
Request path and header example
GET /v1/alerts/timers
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK, along with a list of timers sorted in order from the shortest duration to the longest duration. If no timers are found, Alexa returns an empty list with totalCount set to 0.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"timers": [{
"id": "timer.id.1",
"status": "ON",
"duration": "PT10M",
"triggerTime": "2019-12-03T10:25:30Z",
"createdTime": "2019-12-03T10:15:30Z",
"updatedTime": "2019-12-03T10:15:30Z"
},
{
"id": "timer.id.2",
"status": "PAUSED",
"duration": "PT15M",
"timerLabel": "Pizza",
"createdTime": "2019-12-03T10:15:30Z",
"updatedTime": "2019-12-03T10:12:03Z",
"remainingTimeWhenPaused": "PT3M3S"
}
],
"totalCount": 2,
"nextToken": null
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
List of timers |
Array of objects |
|
|
Uniquely identifies the timer. |
String |
|
|
State of the timer.
|
String |
|
|
Length of the timer interval. |
String |
|
|
(Optional) Name of the timer. The user can reference the timer by this name. |
String |
|
|
Time when the timer expires and alerts the user. Note: Alexa calculates the trigger time based on the duration and the creation time in the customer's time zone.
|
String |
|
|
Time when the timer was created. |
String |
|
|
Time when the timer was last paused, resumed, or stopped. Otherwise, set to |
String |
|
|
(Optional) For paused timers, identifies the remaining time left on the timer. |
String |
|
|
Total number of timers. |
Integer |
|
|
Indicates whether there are more timers to return. At this time, pagination isn't supported. Always set to |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains a list of timers. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25. |
|
|
Requested resource not found or the timer doesn't exist. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Pause timer
Pause the specified timer on the current Alexa-enabled device and save the remaining time. The timer continues when the user resumes the timer.
Request
To pause a timer, you make a POST request to the timers resource.
Request path and header example
POST /v1/alerts/timers/{id}/pause
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Timer ID. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The response has no body.
Response
A successful response returns HTTP 200 OK.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message. If you try to pause a timer with status = PAUSED, Alexa returns HTTP 400 Bad Request with code= TIMER_ALREADY_PAUSED.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Successfully paused the specified timer. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25. |
|
|
Requested resource not found or the timer doesn't exist. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Resume timer
Resume the pause timer. The timer runs for the remaining time unless the user cancels or pauses the timer again.
Request
To resume a timer, you make a POST request to the timers resource.
Request path and header example
POST /v1/alerts/timers/{id}/resume
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Timer ID. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The response has no body.
Response
A successful response returns HTTP 200 OK.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
If you try to pause a timer with status not set to PAUSED, Alexa returns HTTP 400 Bad Request with code= TIMER_IS_NOT_PAUSED.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Successfully resumed the specified timer. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25. |
|
|
Requested resource not found or the timer doesn't exist. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Object definitions
The Timers API defines the following objects.
Operation
The Operation object defines what Alexa does when the timer expires.
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Based on the type value, Alexa plays a chime, announces text, or launches a skill connections task on timer expiration. |
String |
Yes |
|
|
Text and locale information for the announcement. Note: SSML isn't supported.
|
Array of objects |
No |
|
|
Text that Alexa speaks when the timer expires. Note: Alexa appends the following text to the beginning of the announcement: "from <skillname>".
|
String |
Yes |
|
|
Locale where the announcement applies. |
String |
Yes |
|
|
Information about the custom task. |
Object |
No |
|
|
Name of the custom task. |
String |
Yes |
|
|
Version of the task. |
String |
Yes |
|
|
Custom task information to include when Alexa launches the task. |
Object |
No |
|
|
Text and locale information for confirmation announcement. The user must confirm or deny the task. Note: SSML isn't supported.
|
Array of objects |
No |
|
|
Text that Alexa speaks to prompt the user whether to connect to another skill to complete the task. Note: Alexa replaces
continueWithSkillName with the following text: "continue with <skillname>". |
String |
Yes |
|
|
Locale where the announcement applies. |
String |
Yes |
Locale values
The following table shows valid values for the locale property.
| Locale code | Language |
|---|---|
|
|
Arabic (SA) |
|
|
German (DE) |
|
|
English (AU) |
|
|
English (CA) |
|
|
English (UK) |
|
|
English (IN) |
|
|
English (US) |
|
|
Spanish (ES) |
|
|
Spanish (MX) |
|
|
Spanish (US) |
|
|
French (CA) |
|
|
French (FR) |
|
|
Hindi (IN) |
|
|
Italian (IT) |
|
|
Japanese (JP) |
|
|
Dutch (NL) |
|
|
Portuguese (BR) |
Related topics
Last updated: Aug 07, 2024