Alexa.Cooking Interface
The Alexa.Cooking interface describes messages used to direct a cooking appliance to perform an operation and should be implemented by all cooking appliances.
For information about skills and additional interfaces related to cooking, see Build Smart Home Skills for Cooking Appliances.
For the list of locales that are supported for the Cooking interface, see List of Capability Interfaces and Supported Locales.
Utterances
When you use the Alexa.Cooking interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, defrost three pounds of meat in my microwave.
After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.
Discovery
When you discover a cooking device, you specify the properties it supports, but also some configuration values such as whether the endpoint supports remote start and the cooking modes it supports.
Configuration Payload
In addition to the standard discovery format, the Cooking discovery response should include a configuration object with the following fields.
| Property | Description | Type | Required |
|---|---|---|---|
supportedCookingModes |
Specifies the cooking modes supported for this appliance's implementation of the Cooking interface. This array must contain OFF. |
An array of CookingMode Values. | Yes |
supportsRemoteStart |
True to indicates the appliance starts with an Alexa voice command, otherwise false indicates the appliance is set to the specified cooking mode, but does not start until the customer presses the start button on the appliance. The default is false. | Boolean | No |
Example Discovery.Response
The following example shows a Discovery.Response event for a microwave that supports the Cooking interface.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "abc-123-def-456"
},
"payload": {
"endpoints": [{
"endpointId": "uniqueIdOfApplianceEndpoint",
"manufacturerName": "the manufacturer name of the endpoint",
"friendlyName": "Microwave",
"description": "a description that is shown to the customer",
"displayCategories": [
"MICROWAVE"
],
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
},
{
"type": "AlexaInterface",
"interface": "Alexa.Cooking",
"version": "3",
"properties": {
"supported": [{
"name": "cookingMode"
},
{
"name": "cookCompletionTime"
},
{
"name": "isCookCompletionTimeEstimated"
},
{
"name": "cookStartTime"
},
{
"name": "foodItem"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"supportsRemoteStart": false,
"supportedCookingModes": ["OFF", "DEFROST", "REHEAT"]
}
}
]
}]
}
}
}
Directives
SetCookingMode
Request to set a cooking mode for an appliance. May be sent if the food requested by the customer is not a preset option on the microwave.
User: Alexa, defrost three pounds of meat in my microwave
Example Request
{
"directive": {
"header": {
"namespace": "Alexa.Cooking",
"name": "SetCookingMode",
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "appliance-001",
"cookie": {}
},
"payload": {
"foodItem": {
"foodName": "meat",
"foodCategory": "BEEF",
"foodQuantity": {
"@type": "Weight",
"value": "3",
"unit": "POUND"
}
},
"cookingMode": {
"value": "DEFROST"
}
}
}
}
Payload details
| Field | Description | Type | Required |
|---|---|---|---|
cookingMode |
Indicates the cooking mode for the operation. | A CookingMode Object or a CookingMode String. | Yes |
foodItem |
The type of food to cook, if it needs to be specified. | FoodItem object | No |
Properties and Events
For this capability, you must reply:
- Synchronously, which means you send a Response to Alexa from the Lambda function.
When you send a Response, you should include the state of the interface properties in the context of the message.
Properties
| Property Name | Type | Description |
|---|---|---|
cookingMode |
A CookingMode Object or a CookingMode String. | The cooking mode, such as defrost or reheat. For more information, see CookingMode Values. |
cookStartTime |
DateTime | The time cooking started. |
cookCompletionTime |
DateTime | The time cooking completed. |
isCookCompletionTimeEstimated |
Boolean | true to indicate the cookCompletionTime provided is estimated; otherwise false. The default is false. |
foodItem |
FoodItem | The food that is being cooked. This could be provided by the user or another means such as a camera or sensor on the appliance. |
Response
If SetCookingMode directive was successfully handled, respond synchronously with a Response event, and include the values of the endpoint properties in the context of the message. The following example shows a response for an endpoint that supports Cooking and TimeController.
Example Response
{
"context":{
"properties":[
{
"namespace":"Alexa.Cooking",
"name":"cookingMode",
"value":"TIMECOOK",
"timeOfSample":"2017-08-31T23:30:00Z",
"uncertaintyInMilliseconds":0
},
{
"namespace":"Alexa.Cooking",
"name":"cookCompletionTime",
"value":"2017-08-31T23:36:15Z",
"timeOfSample":"2017-08-31T23:30:00Z",
"uncertaintyInMilliseconds":0
},
{
"namespace":"Alexa.Cooking",
"name":"isCookCompletionTimeEstimated",
"value":false,
"timeOfSample":"2017-08-31T23:30:00Z",
"uncertaintyInMilliseconds":0
},
{
"namespace":"Alexa.Cooking",
"name":"cookStartTime",
"value":"2017-08-31T23:30:00Z",
"timeOfSample":"2017-08-31T23:30:00Z",
"uncertaintyInMilliseconds":0
},
{
"namespace":"Alexa.Cooking",
"name":"foodItem",
"value":{
"foodName":"Copper river salmon",
"foodCategory":"FISH",
"foodQuantity":{
"@type":"Weight",
"value":"2.5",
"unit":"POUND"
}
},
"timeOfSample":"2017-08-31T23:30:00Z",
"uncertaintyInMilliseconds":0
},
{
"namespace":"Alexa.Cooking.TimeController",
"name":"cookTime",
"value":"PT6M15S",
"timeOfSample":"2017-08-31T23:30:00Z",
"uncertaintyInMilliseconds":0
},
{
"namespace":"Alexa.Cooking.TimeController",
"name":"powerLevel",
"value":{
"@type":"EnumeratedPowerLevel",
"value":"HIGH"
},
"timeOfSample":"2017-08-31T23:30:00Z",
"uncertaintyInMilliseconds":0
}
]
},
"event":{
"header":{
"namespace":"Alexa",
"name":"Response",
"messageId":"abc-123-def-456",
"correlationToken":"dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion":"3"
},
"endpoint":{
"scope":{
"type":"BearerToken",
"token":"access-token-from-Amazon"
},
"endpointId":"appliance-001"
},
"payload":{
}
}
}
ErrorResponse
You should reply with an error if you cannot complete the customer request for some reason. For cooking-specific errors such as an appliance door is open, see Alexa.Cooking.ErrorResponse. For generic errors, such as a device is offline, see Error.Response.
Related Interfaces
| Interface | Description |
|---|---|
| Alexa.Cooking.PresetController | Provides directives for cooking with appliance preset options. |
| Alexa.Cooking.TimeController | Provides directives for cooking by time interval. |
| Alexa.TimeHoldController | Provides directives for pausing or resuming an endpoint. |