Alexa.InventoryLevelSensor Interface
Implement the Alexa.InventoryLevelSensor interface in your Alexa skill so that you can report the amount of a consumable that your device has remaining. For example, if your device is a printer, you can report the amount of ink or toner that the printer has remaining. You can implement multiple instances of InventoryLevelSensor for multiple consumables, such as a printer with separate storage for cyan, yellow, magenta, and black ink or toner.
If you report when your device uses a consumable, implement the InventoryUsageSensor interface instead. If the consumable that you track has an unknown lifespan, implement the InventoryLevelUsageSensor interface instead.
For the list of languages that the InventoryLevelSensor interface supports, see List of Alexa Interfaces and Supported Languages.
Dash Replenishment IDs
By using Dash Replenishment through Alexa, the user of your device can sign up to order more of each consumable when the consumable level is low. For details, see What is Dash Replenishment? and Dash Replenishment Account Setup.
When you sign your device up for Dash Replenishment, you set up a replenishment id for each consumable in your device. The replenishment id identifies what (one or more) products the user can order to replace the consumable. When the user sets up replenishment in their account, they choose the specific product that they want to order. Users can't set up replenishment until you provide your replenishment ids to Alexa. You can provide the replenishment ids for your device to Alexa in the following ways:
- If you already have your replenishment IDs at the time of device discovery, provide them in your discover response.
- You can provide your replenishment IDs later in an AddOrUpdateReport message.
Properties
The Alexa.InventoryLevelSensor interface uses the level property to represent the current amount of a consumable that a device has remaining.
You can express level as one of the following types: count, percentage, volume, or weight. For volume and weight, you include the unit of measure.
An endpoint can support multiple sensors, so you must always include the instance attribute for a level property. You identify your instance names in your discovery response.
Level property example
{
"namespace": "Alexa.InventoryLevelSensor",
"instance": "InkSensor.Cyan",
"name": "level",
"value": {
"@type": "Volume",
"value": 5,
"unit": "MILLILITER"
}
}
Discovery
You describe endpoints that support Alexa.InventoryLevelSensor using the standard discovery mechanism described in Alexa.Discovery.
Set proactivelyReported to true for the properties that you proactively report to Alexa in a change report.
For the full list of display categories, see display categories.
In addition to the usual discovery response fields, for each InventoryLevelSensor entry in the capabilities array, include the following fields.
| Field | Description | Type |
|---|---|---|
instance |
The name of the sensor, for example Ink.Cyan or Ink.Yellow. |
String |
configuration.measurement |
The way you measure the consumable. One of count, percentage, volume, or weight. For volume and weight, include the unit of measure. | Object |
configuration.replenishment |
The Dash Replenishment ID for the consumable. | Object |
capabilityResources |
Friendly names that customers can use to interact with the sensor. | A CapabilityResources object. |
Discover response example
The following example shows a Discover.Response message for a printer that supports the Alexa.InventoryLevelSensor interface.
messageId in the header of your events must be unique, as described in Header object.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<a unique identifier, preferably a version 4 UUID>"
},
"payload": {
"endpoints": [
{
"endpointId": "unique ID of the endpoint",
"manufacturerName": "Printer Plus",
"description": "Smart Printer by Printer Maker Plus",
"friendlyName": "Printer",
"displayCategories": [
"OTHER"
],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.InventoryLevelSensor",
"instance": "InkSensor.Cyan",
"version": "3",
"properties": {
"supported": [
{
"name": "level"
}
],
"retrievable": false,
"proactivelyReported": true
},
"configuration": {
"measurement": {
"@type": "Volume",
"unit": "MILLILITER"
},
"replenishment": {
"@type": "DashReplenishmentId",
"value": "<the replenishment ID for refill options>"
}
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Cyan ink",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Encre cyan",
"locale": "fr-FR"
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.InventoryLevelSensor",
"instance": "PaperSensor.FrontTray",
"version": "3",
"properties": {
"supported": [
{
"name": "level"
}
],
"retrievable": false,
"proactivelyReported": true
},
"configuration": {
"measurement": {
"@type": "Count"
},
"replenishment": {
"@type": "DashReplenishmentId",
"value": "<the replenishment ID for refill options>"
}
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Front tray",
"locale": "en-US"
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"retrievable": true,
"proactivelyReported": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [
{
"name": "connectivity"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
AddOrUpdateReport
You must proactively send an Alexa.Discovery.AddOrUpdateReport message if the feature support of your endpoint changes. For example, if you don't have the replenishment IDs for your consumables at the time of initial device discovery, you can provide the replenishment IDs to Alexa later by sending an AddOrUpdateReport message. For details, see AddOrUpdateReport event.
AddOrUpdateReport event example
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "<a unique identifier, preferably a version 4 UUID>"
},
"payload": {
"endpoints": [
{
"endpointId": "unique ID of the endpoint",
"manufacturerName": "Printer Plus",
"description": "Smart Printer by Printer Maker Plus",
"friendlyName": "Printer",
"displayCategories": [
"OTHER"
],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.InventoryLevelSensor",
"instance": "InkSensor.Cyan",
"version": "3",
"properties": {
"supported": [
{
"name": "level"
}
],
"retrievable": true,
"proactivelyReported": true
},
"configuration": {
"measurement": {
"@type": "Volume",
"unit": "MILLILITER"
},
"replenishment": {
"@type": "DashReplenishmentId",
"value": "<the replenishment ID for refill options>"
}
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Cyan ink",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Encre cyan",
"locale": "fr-FR"
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.InventoryLevelSensor",
"instance": "PaperSensor.FrontTray",
"version": "3",
"properties": {
"supported": [
{
"name": "level"
}
],
"retrievable": true,
"proactivelyReported": true
},
"configuration": {
"measurement": {
"@type": "Count"
},
"replenishment": {
"@type": "DashReplenishmentId",
"value": "<the replenishment ID for refill options>"
}
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Front tray",
"locale": "en-US"
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"retrievable": true,
"proactivelyReported": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Change reporting
You send a ChangeReport event to proactively report changes in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.
ChangeReport event example
In the following example you notify Alexa about the remaining levels of each consumable after a daily check of all sensors.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<a unique identifier, preferably a version 4 UUID>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "endpoint ID"
},
"payload": {
"change": {
"cause": {
"type": "PERIODIC_POLL"
},
"properties": [
{
"namespace": "Alexa.InventoryLevelSensor",
"instance": "InkSensor.Cyan",
"name": "level",
"value": {
"@type": "Volume",
"value": 5,
"unit": "MILLILITER"
},
"timeOfSample": "2019-10-31T17:00:00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.InventoryLevelSensor",
"instance": "PaperSensor.FrontTray",
"name": "level",
"value": {
"@type": "Count",
"value": 200
},
"timeOfSample": "2019-10-31T17:00:00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2019-10-31T17:00:00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2019-10-31T17:00:00Z",
"uncertaintyInMilliseconds": 0
}
}