Alexa.Health.Sleep Interface
The Alexa.Health.Sleep
interface describes messages that you can use to develop Alexa skills for your sleep tracking apps and devices. You can develop your skill as a stand-alone skill, or you can integrate it with a device, such as a wearable wrist device. Your customers can track sleep for themselves, their children, and other family members. For an overview of the Alexa.Health
interfaces, see Understand the Baby Activity Skill API.
For the list of locales that are supported for the Sleep
interface, see List of Capability Interfaces and Supported Locales.
Utterances
When you use the Alexa.Health.Sleep
interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, record sleep for thirty minutes.
Alexa, record sleep for my baby from three pm to five-thirty pm today.
Alexa, when did my baby start sleeping?
Alexa, how many hours has Jane slept for today?
Alexa, start sleep tracking.
Alexa, stop sleep tracking.
After the customer says one of these utterances, Alexa sends a corresponding directive to your skill. You identify which directives you support, and for which customers, in the user profile report. You handle the directive and send a response event back to Alexa.
Before you submit your skill for certification, verify that you correctly handle the utterances in the testing guide.
User profile report
When a customer enables your Alexa skill, post a profile report message to Alexa. Your customers create their profiles in your app, and you create an identifier to track them in your app. Send the same identifier to Alexa as profileId
in the profile report. If a customer adds, updates, or deletes a profile in your app, post a new profile report message to Alexa.
Identify the directives that your skill supports for each profile as supportedOperations
in the profile report. The Get
directive is always required. Requirements for other directives are specified in the Directives section.
You can send multiple profiles and multiple capabilities in the profile report. For more information, see User Profiles.
User profile report example
{
"report": {
"messageId": "<message id>",
"profiles": [
{
"profileId": "<profile id>",
"name": {
"firstName": "Baby",
"lastName": "Doe",
"nickNames": ["Baby", "Junior"]
},
"capabilities": [
{
"name": "Alexa.Health.Sleep",
"type": "AlexaInterface",
"version": "1",
"supportedOperations": ["Add", "Get", "Start", "Pause", "Resume", "Cancel", "Stop"]
}
]
}
]
}
}
The sleepMeasurement object
The Alexa.Health.Sleep
interface uses the sleepMeasurement
object as the primary data object.
Sleep measurement details
Field | Description | Type | Required |
---|---|---|---|
startTime |
The time that sleep started, specified in UTC. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
endTime |
The time that sleep ended, specified in UTC. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
sleep |
The duration of the sleep session. Duration might not equal the difference between the end time and the start time, for example if the sleep was paused interrupted. | A sleep object that contains a duration string. | Yes |
Sleep measurement example
{
"sleepMeasurement": {
"startTime": "2018-03-14T22:30Z",
"endTime": "2018-03-15T06:30Z",
"sleep": {
"duration": "PT8H"
}
}
}
Directives
Add directive
Support the Add
directive so that customers can log a sleep session. The Add
directive is optional if voice interaction is not required. For example, a wearable device that tracks sleep based on movement can record sleep without voice interaction.
The following example shows a customer utterance:
Alexa, record sleep at ten am.
Add directive payload details
Field | Description | Type | Required |
---|---|---|---|
sleepMeasurement |
The sleep measurement to add. | A sleepMeasurement object. | Yes |
Add directive example
{
"directive": {
"header": {
"namespace": "Alexa.Health.Sleep",
"name": "Add",
"messageId": "<message id>",
"payloadVersion": "1"
},
"profile": {
"scope": {
"token": "<an OAuth2 bearer token>"
},
"profileId": "<the identifier for the profile to associate with the sleep session>"
},
"payload": {
"sleepMeasurement": {
"startTime": "2018-03-14T22:30Z",
"endTime": "2018-03-15T06:30Z",
"sleep": {
"duration": "PT8H"
}
}
}
}
}
Add response event
If you handle an Add
directive successfully, respond with an AddResponse
event.
AddResponse event payload details
Field | Description | Type | Required |
---|---|---|---|
entryId |
Your identifier for the record that you added. | String | Yes |
AddResponse event example
{
"event": {
"header": {
"namespace": "Alexa.Health.Sleep",
"name": "AddResponse",
"messageId": "<message id>",
"payloadVersion": "1",
},
"payload": {
"entryId": "<entry id>"
}
}
}
Add directive error handling
If you can't handle an Add
directive successfully, respond with an Alexa.Health.ErrorResponse event.
Start directive
Support the Start
directive so that customers can begin timing a sleep session. You can also start a timer retroactively. The Start
directive is not required.
The following examples show customer utterances:
Alexa, start sleep for John.
Alexa, start sleep for John starting ten minutes ago.
Start directive payload details
Field | Description | Type | Required |
---|---|---|---|
startTime |
The time that sleep started, specified in UTC. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
Start directive example
{
"directive": {
"header": {
"namespace": "Alexa.Health.Sleep",
"name": "Start",
"messageId": "<message id>",
"payloadVersion": "1"
},
"profile": {
"scope": {
"token": "<an OAuth2 bearer token>"
},
"profileId": "<the identifier for the profile to associate with the sleep session>"
},
"payload": {
"startTime": "2018-03-14T22:30Z"
}
}
}
Start response event
If you handle a Start
directive successfully, respond with a standard Alexa.Response
event. For more information, see Alexa.Response Interface.
Start directive error handling
If you can't handle a Start
directive successfully, respond with an Alexa.Health.ErrorResponse event. Use the TIMER_ALREADY_RUNNING
error type if the timer is already running.
Pause directive
Support the Pause
directive so that customers can pause a sleep timer. You can pause a sleep timer retroactively. The Pause
directive is not required, and is not allowed, unless the Start
directive is supported.
The following examples show customer utterances:
Alexa, pause sleep for Jane.
Alexa, pause sleep for Jane ten minutes ago.
Pause directive payload details
Field | Description | Type | Required |
---|---|---|---|
pauseTime |
The time that sleep paused, specified in UTC. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
Pause directive example
{
"directive": {
"header": {
"namespace": "Alexa.Health.Sleep",
"name": "Pause",
"messageId": "<message id>",
"payloadVersion": "1"
},
"profile": {
"scope": {
"token": "<an OAuth2 bearer token>"
},
"profileId": "<the identifier for the profile associated with the sleep session>"
},
"payload": {
"pauseTime": "2018-03-15T01:30Z"
}
}
}
Pause response event
If you handle a Pause
directive successfully, respond with a standard Alexa.Response
event. For more information, see Alexa.Response Interface.
Pause directive error handling
If you can't handle a Pause
directive successfully, respond with an Alexa.Health.ErrorResponse event. Use the TIMER_NOT_RUNNING
or TIMER_ALREADY_PAUSED
error type if appropriate.
Resume directive
Support the Resume
directive so that customers can resume a sleep timer. You can resume a sleep timer retroactively. The Resume
directive is not required, and is not allowed, unless the Start
directive is supported.
The following examples show customer utterances:
Alexa, resume sleep for Jane.
Alexa, resume sleep for Jane five minutes ago.
Resume directive payload details
Field | Description | Type | Required |
---|---|---|---|
resumeTime |
The time that sleep resumed, specified in UTC. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
Resume directive example
{
"directive": {
"header": {
"namespace": "Alexa.Health.Sleep",
"name": "Resume",
"messageId": "<message id>",
"payloadVersion": "1"
},
"profile": {
"scope": {
"token": "<an OAuth2 bearer token>"
},
"profileId": "<the identifier for the profile associated with the sleep session>"
},
"payload": {
"resumeTime": "2018-03-15T02:30Z"
}
}
}
Resume response event
If you handle a Resume
directive successfully, respond with a standard Alexa.Response
event. For more information, see Alexa.Response Interface.
Resume directive error handling
If you can't handle a Resume
directive successfully, respond with an Alexa.Health.ErrorResponse event. Use the TIMER_NOT_RUNNING
or TIMER_NOT_PAUSED
error type if appropriate.
Cancel directive
Support the Cancel
directive so that customers can cancel a sleep timer. The Cancel
directive is not required, and is not allowed, unless the Start
directive is supported.
The following example shows a customer utterance:
Alexa, cancel sleep for Jane.
Cancel directive payload details
The payload for the Cancel
directive is empty.
Cancel directive example
{
"directive": {
"header": {
"namespace": "Alexa.Health.Sleep",
"name": "Cancel",
"messageId": "<message id>",
"payloadVersion": "1"
},
"profile": {
"scope": {
"token": "<an OAuth2 bearer token>"
},
"profileId": "<the identifier for the profile associated with the sleep session>"
},
"payload": {
}
}
}
Cancel response event
If you handle a Cancel
directive successfully, respond with a standard Alexa.Response
event. For more information, see Alexa.Response Interface.
Cancel directive error handling
If you can't handle a Cancel
directive successfully, respond with an Alexa.Health.ErrorResponse event. Use the TIMER_NOT_RUNNING
error type if the timer is not running.
Stop directive
Support the Stop
directive so that customers can stop timing a sleep session. You can also stop a sleep timer retroactively. The Stop
directive is not required, and is not allowed, unless the Start
directive is supported.
The following examples show customer utterances:
Alexa, stop sleep for John.
Alexa, John woke up ten minutes ago.
Stop directive payload details
Field | Description | Type | Required |
---|---|---|---|
stopTime |
The time that sleep stopped, specified in UTC. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
Stop directive example
{
"directive": {
"header": {
"namespace": "Alexa.Health.Sleep",
"name": "Stop",
"messageId": "<message id>",
"payloadVersion": "1"
},
"profile": {
"scope": {
"token": "<an OAuth2 bearer token>"
},
"profileId": "<the identifier for the profile associated with the sleep session>"
},
"payload": {
"stopTime": "2018-03-15T06:30Z"
}
}
}
Stop response event
If you handle a Stop
directive successfully, respond with a StopResponse
event.
StopResponse event payload details
Field | Description | Type | Required |
---|---|---|---|
duration |
The duration of the sleep session. | A sleep object that contains a duration string. | Yes |
entryId |
Your identifier for the record that you added. You can use this identifier to delete the record in case the customer added the data by mistake. | String | Yes |
StopResponse event example
{
"event": {
"header": {
"namespace": "Alexa.Health.Sleep",
"name": "StopResponse",
"messageId": "<message id>",
"payloadVersion": "1",
},
"payload": {
"duration": "PT30M",
"entryId": "<entry id>"
}
}
}
Stop directive error handling
If you can't handle a Stop
directive successfully, respond with an Alexa.Health.ErrorResponse event. Use the TIMER_NOT_RUNNING
error type if the timer is not running.
Get directive
Support the Get
directive so that customers can retrieve one or more sleep measurements. The Get
directive is required.
The following examples show customer utterances:
Alexa, how long did my baby sleep yesterday?
Alexa, how many hours has Jane slept for today?
Get directive payload details
Field | Description | Type | Required |
---|---|---|---|
maxResults |
The maximum number of results to return in the current page of results. Results beyond this number are paginated. Specify a number greater than zero. | Integer | Yes |
nextToken |
A token to retrieve additional results if the results are paginated and there are more results. | String | No |
filterParameters |
An array of filter parameter objects that filters the results of the query. Use "startTime" for the fieldName in your filter parameters when you retrieve sleep measurements. |
Array | No |
sortParameters |
An array of sort parameter objects that sorts the results of the query. | Array | No |
Get directive example
{
"directive": {
"header": {
"namespace": "Alexa.Health.Sleep",
"name": "Get",
"messageId": "<message id>",
"payloadVersion": "1"
},
"profile": {
"scope": {
"token": "<an OAuth2 bearer token>"
},
"profileId": "<the identifier for the profile associated with the sleep measurements>"
},
"payload": {
"queryParameters": {
"maxResults": "3",
"nextToken": "<token indicating starting offset for next paginated result>",
"filterParameters": [
{
"fieldName": "startTime",
"comparisonOperator": "GTE",
"value": "2018-05-30T00:00:00Z"
}
],
"sortParameters": [
{
"fieldName": "startTime",
"order": "ASC"
}
]
}
}
}
}
Get response event
If you handle a Get
directive successfully, respond with a GetResponse
event.
GetResponse event payload details
Field | Description | Type | Required |
---|---|---|---|
nextToken |
A token to retrieve additional results if the results are paginated and there are more results. | String | No |
sleepMeasurements |
The results of the query. | An array of sleepMeasurement objects. | Yes |
GetResponse event example
{
"event": {
"header": {
"namespace": "Alexa.Health.Sleep",
"name": "GetResponse",
"messageId": "<message id>",
"payloadVersion": "1"
},
"payload":{
"nextToken": "4",
"sleepMeasurements": [
{
"startTime": "2018-05-30T22:00Z",
"endTime": "2018-05-31T06:00Z",
"sleep": {
"duration": "PT8H"
}
},
{
"startTime": "2018-05-31T14:00Z",
"endTime": "2018-05-31T14:30Z",
"sleep": {
"duration": "PT30M"
}
},
{
"startTime": "2018-05-31T22:30Z",
"endTime": "2018-06-01T06:30Z",
"sleep": {
"duration": "PT8H"
}
}
]
}
}
}
Get directive error handling
If you can't handle a Get
directive successfully, respond with an Alexa.Health.ErrorResponse event. Use the INVALID_NEXT_TOKEN
error type if the nextToken
is inconsistent with the filter and sort parameters. For more information, see Paginating Results.
Related interfaces
Interface | Description |
---|---|
Alexa.Health.Weight | Describes messages for tracking weight measurements. |
Alexa.Health.InfantFeeding | Describes messages for tracking and timing infant feeding. |
Alexa.Health.DiaperChange | Describes messages for tracking diaper changes. |