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 Request Access to Send Messages to Your Skill.

Operations

The Timers API includes the following operations.

Operation HTTP method and URI

Create timer

POST /v1/alerts/timers

Cancel all timers

DELETE /v1/alerts/timers

Cancel timer

DELETE /v1/alerts/timers/{id}

Get timer

GET /v1/alerts/timers/{id}

List timers

GET /v1/alerts/timers

Pause timer

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

Resume timer

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

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

Copied to clipboard.

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

access token

Header

Access token for the customer.
Set to apiAccessToken.

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

duration

Length of time to run the timer.
For example, if the duration is 90 minutes, the timer goes off in 90 minutes from creation time. Defined in ISO 8601 duration format, PT*H*H*M*M*SS*S.
Maximum timer length: 2 hours.

String

Yes

timerLabel

Name of the timer. The user can reference the timer by this name.
Valid value: Up to 256 characters.

String

No

creationBehavior

Defines the behavior at timer creation.

Object

Yes

creationBehavior.displayExperience

Determines the timer behavior on an Alexa-enabled device with a screen.

Object

Yes

creationBehavior.displayExperience.visibility

Determines whether to display or hide the timer on an Alexa-enabled device with a screen.
Valid values: VISIBLE, HIDDEN.

String

Yes

triggeringBehavior

Defines what Alexa does when the timer expires.

Object

Yes

triggeringBehavior.operation

Defines the operation to perform when the timer expires.

Operation object

Yes

triggeringBehavior.notificationConfig

Defines whether to play a notification when the timer expires.

Object

Yes

triggeringBehavior.notificationConfig.playAudible

Indicates whether the timer expiration is audible.
Must be set to true for type = NOTIFY_ONLY. When set to true, Alexa plays the notification until the user says, "Alexa, stop." to dismiss the timer.

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

id

Uniquely identifies the timer.

String

status

State of the timer.
Valid values: ON, OFF, PAUSED.

  • ON – The timer is active and rings at triggerTime, or if triggerTime passed, the timer is ringing now.
  • OFF – The timer expired or the user cancelled the timer.
  • PAUSED – The timer was on, but now the timer is paused. The user can resume the timer.

String

duration

Length of the timer interval.
Defined in ISO 8601 duration format, PT*H*H*M*M*SS*S.

String

timerLabel

(Optional) Name of the timer. The user can reference the timer by this name.
Valid value: Up to 256 characters.

String

triggerTime

Time when the timer expires and alerts the user.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

createdTime

Time when the timer was created.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

updatedTime

Time when the timer was last paused, resumed, or stopped. Otherwise, set to createdTime.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

remainingTimeWhenPaused

(Optional) For paused timers, identifies the remaining time left on the timer.
Defined in ISO 8601 curation format, YYYY-MM-DDThh:mm:ssZ.

String

HTTP status codes

Status Description

200 OK

Response body contains the timer information.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Request duration format incorrect.",
     "code": "INVALID_DURATION_FORMAT"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25.

404 Not Found

Requested resource not found or the timer doesn't exist.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

access token

Header

Access token for the customer.
For in-session requests, set to apiAccessToken.
For out-of-session requests, set to an LWA token.

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

200 OK

Successfully cancelled all timers for the customer for this skill.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Request duration format incorrect.",
     "code": "INVALID_DURATION_FORMAT"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25.

404 Not Found

Requested resource not found or the timer doesn't exist.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

id

Path

Timer ID.

String

Yes

access token

Header

Access token for the customer.
For in-session requests, set to apiAccessToken.
For out-of-session requests, set to an LWA token.

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

200 OK

Successfully cancelled the specified timer.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Request duration format incorrect.",
     "code": "INVALID_DURATION_FORMAT"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25.

404 Not Found

Requested resource not found or the timer doesn't exist.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

id

Path

Timer ID.

String

Yes

access token

Header

Access token for the customer.
For in-session requests, set to apiAccessToken.
For out-of-session requests, set to an LWA token.

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

id

Uniquely identifies the timer.

String

status

State of the timer.
Valid values: ON, OFF, PAUSED.

  • ON – The timer is active and rings at triggerTime, or if triggerTime passed, the timer is ringing now.
  • OFF – The timer expired or the user cancelled the timer.
  • PAUSED – The timer was on, but now the timer is paused. The user can resume the timer.

String

duration

Length of the timer interval.
Defined in ISO 8601 duration format, PT*H*H*M*M*SS*S.

String

timerLabel

(Optional) Name of the timer. The user can reference the timer by this name.
Valid value: Up to 256 characters.

String

triggerTime

Time when the timer expires and alerts the user.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

createdTime

Time when the timer was created.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

updatedTime

Time when the timer was last paused, resumed, or stopped. Otherwise, set to createdTime.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

remainingTimeWhenPaused

(Optional) For paused timers, identifies the remaining time left on the timer.
Defined in ISO 8601 curation format, YYYY-MM-DDThh:mm:ssZ.

String

HTTP status codes

Status Description

200 OK

Response body contains the timer information.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Request duration format incorrect.",
     "code": "INVALID_DURATION_FORMAT"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25.

404 Not Found

Requested resource not found or the timer doesn't exist.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

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 householdlists resource.

Request path and header example

Copied to clipboard.

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

access token

Header

Access token for the customer.
For in-session requests, set to apiAccessToken.
For out-of-session requests, set to an LWA token.

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

timers[]

List of timers

Array of objects

timers[].id

Uniquely identifies the timer.

String

timers[].status

State of the timer.
Valid values: ON, OFF, PAUSED.

  • ON – The timer is active and rings at triggerTime, or if triggerTime passed, the timer is ringing now.
  • OFF – The timer expired or the user cancelled the timer.
  • PAUSED – The timer was on, but now the timer is paused. The user can resume the timer.

String

timers[].duration

Length of the timer interval.
Defined in ISO 8601 duration format, PT*H*H*M*M*SS*S.

String

timers[].timerLabel

(Optional) Name of the timer. The user can reference the timer by this name.
Valid value: Up to 256 characters.

String

timers[].triggerTime

Time when the timer expires and alerts the user.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

timers[].createdTime

Time when the timer was created.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

timers[].updatedTime

Time when the timer was last paused, resumed, or stopped. Otherwise, set to createdTime.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

timers[].remainingTimeWhenPaused

(Optional) For paused timers, identifies the remaining time left on the timer.
Defined in ISO 8601 curation format, YYYY-MM-DDThh:mm:ssZ.

String

totalCount

Total number of timers.

Integer

nextToken

Indicates whether there are more timers to return. At this time, pagination isn't supported. Always set to null.

String

HTTP status codes

Status Description

200 OK

Response body contains a list of timers.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Request duration format incorrect.",
     "code": "INVALID_DURATION_FORMAT"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25.

404 Not Found

Requested resource not found or the timer doesn't exist.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

id

Path

Timer ID.

String

Yes

access token

Header

Access token for the customer.
Set to apiAccessToken.

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

200 OK

Successfully paused the specified timer.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Request duration format incorrect.",
     "code": "INVALID_DURATION_FORMAT"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25.

404 Not Found

Requested resource not found or the timer doesn't exist.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

id

Path

Timer ID.

String

Yes

access token

Header

Access token for the customer.
Set to apiAccessToken.

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

200 OK

Successfully resumed the specified timer.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Request duration format incorrect.",
     "code": "INVALID_DURATION_FORMAT"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed. For example, the maximum number of timers created reached 25.

404 Not Found

Requested resource not found or the timer doesn't exist.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

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

type

Based on the type value, Alexa plays a chime, announces text, or launches a skill connections task on timer expiration.
Valid values: NOTIFY_ONLY, ANNOUNCE, LAUNCH_TASK.

String

Yes

textToAnnounce[]

Text and locale information for the announcement.
Valid for type = ANNOUNCE only.
If playAudible is false, Alexa speaks the text when the timer expires. If playAudible is true, Alexa speaks the text when the user dismisses the timer.

Array of objects

No

textToAnnounce[].text

Text that Alexa speaks when the timer expires.

String

Yes

textToAnnounce[].locale

Locale where the announcement applies.

String

Yes

task

Information about the custom task.
Valid for type = LAUNCH_TASK only.

Object

No

task.name

Name of the custom task.

String

Yes

task.version

Version of the task.

String

Yes

task.input

Custom task information to include when Alexa launches the task.
Format as key-value pair.

Object

No

textToConfirm[]

Text and locale information for confirmation announcement. The user must confirm or deny the task.
Valid for type = LAUNCH_TASK only.
If playAudible is false, Alexa speaks the text when the timer expires. If playAudible is true, Alexa speaks the text when the user dismisses the timer.

Array of objects

No

textToConfirm[].text

Text that Alexa speaks to prompt the user whether to connect to another skill to complete the task.
You must include {continueWithSkillName} in the text.

String

Yes

textToConfirm[].locale

Locale where the announcement applies.

String

Yes

Locale values

The following table shows valid values for the locale property.

Locale code Language

ar-SA

Arabic (SA)

de-DE

German (DE)

en-AU

English (AU)

en-CA

English (CA)

en-GB

English (UK)

en-IN

English (IN)

en-US

English (US)

es-ES

Spanish (ES)

es-MX

Spanish (MX)

es-US

Spanish (US)

fr-CA

French (CA)

fr-FR

French (FR)

hi-IN

Hindi (IN)

it-IT

Italian (IT)

ja-JP

Japanese (JP)

pt-BR

Portuguese (BR)