Alexa.Health.Weight Interface
The Alexa.Health.Weight
interface describes messages that you can use to develop Alexa skills for your weight tracking apps and devices. You can develop your skill as a stand-alone skill, or you can integrate it with a smart home device, such as a scale. Your customers can track weight 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 Weight
interface, see List of Capability Interfaces and Supported Locales.
Utterances
When you use the Alexa.Health.Weight
interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, track weight of one hundred seventy pounds.
Alexa, I weighed one hundred forty-nine pounds yesterday.
Alexa, how much did Jane weigh on May thirtieth?
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": "Jane",
"lastName": "Doe",
"nickNames": ["Janie", "Mom"]
},
"capabilities": [
{
"name": "Alexa.Health.Weight",
"type": "AlexaInterface",
"version": "1",
"supportedOperations": ["Add", "Get"]
}
]
}
]
}
}
The weightMeasurement object
The Alexa.Health.Weight
interface uses the weightMeasurement
object as the primary data object.
Weight measurement details
Field | Description | Type | Required |
---|---|---|---|
measurementTime |
The time of the weight measurement, specified in UTC. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
weight |
The weight in pounds or kilograms. | A weight object. | Yes |
Weight measurement example
{
"weightMeasurement": {
"measurementTime": "2018-05-30T08:15Z",
"weight": {
"value": "9.125",
"unit": "POUND",
}
}
}
Directives
Add directive
Support the Add
directive so that customers can add weight measurements. The Add
directive is optional if voice interaction is not required. For example, a smart scale can record a customer's weight without voice interaction.
The following example shows a customer utterance:
Alexa, track weight of ten point two five pounds this morning.
Add directive payload details
Field | Description | Type | Required |
---|---|---|---|
weightMeasurement |
The weight measurement to add. | A weightMeasurement object. | Yes |
Add directive example
{
"directive": {
"header": {
"namespace": "Alexa.Health.Weight",
"name": "Add",
"messageId": "<message id>",
"payloadVersion": "1"
},
"profile": {
"scope": {
"token": "<an OAuth2 bearer token>"
},
"profileId": "<the identifier for the profile to associate with the weight measurement>"
},
"payload": {
"weightMeasurement": {
"measurementTime": "2018-05-30T08:15Z",
"weight": {
"value": "9.125",
"unit": "POUND",
}
}
}
}
}
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.Weight",
"name": "AddResponse",
"payloadVersion": "1",
"messageId": "<message id>"
},
"payload": {
"entryId": "<entry id>"
}
}
}
Add directive error handling
If you can't handle an Add
directive successfully, respond with an Alexa.Health.ErrorResponse event.
Get directive
Support the Get
directive so that customers can retrieve one or more weight measurements. The Get
directive is required.
The following examples show customer utterances:
Alexa, what was my baby's last weight?
Alexa, what was my baby's weight on May thirtieth?
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 "measurementTime" for the fieldName in your filter parameters when you retrieve weight 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.Weight",
"name": "Get",
"messageId": "<message id>",
"payloadVersion": "1"
},
"profile": {
"scope": {
"token": "<an OAuth2 bearer token>"
},
"profileId": "<the identifier for the profile associated with the weight measurements>"
},
"payload": {
"queryParameters": {
"maxResults": "2",
"nextToken": "<token indicating starting offset for next paginated result>",
"filterParameters": [
{
"fieldName": "measurementTime",
"operator": "GTE",
"value": "2018-05-30T00:00:00Z"
}
],
"sortParameters": [
{
"fieldName": "measurementTime",
"order": "DESC"
}
]
}
}
}
}
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 |
weightMeasurements |
The results of the query. | An array of weightMeasurement objects. | Yes |
GetResponse event example
{
"event": {
"header": {
"namespace": "Alexa.Health.Weight",
"name": "GetResponse",
"messageId": "<message id>",
"payloadVersion": "1"
},
"payload": {
"nextToken": "3",
"weightMeasurements": [
{
"measurementTime": "2018-05-30T08:15Z",
"weight": {
"value": "9.125",
"unit": "POUND"
}
},
{
"measurementTime": "2018-05-30T22:30Z",
"weight": {
"value": "9.250",
"unit": "POUND"
}
}
]
}
}
}
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.Sleep | Describes messages for tracking and timing sleep. |
Alexa.Health.InfantFeeding | Describes messages for tracking and timing infant feeding. |
Alexa.Health.DiaperChange | Describes messages for tracking diaper changes. |