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.

Discovery
Directives
- SetCookingMode
Properties and Events
Related Interfaces

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`.	Array of CookingMode objects that must contain `OFF`.	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": "ff746d98-ab02-4c9e-9d0d-b44711658414"
        },
        "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

The control and query directives in this interface are supported in skills that target the following languages:

English (US)

See Develop Smart Home Skills in Multiple Languages for more information.

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": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "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.	CookingMode object	Yes
`foodItem`	The type of food to cook, if it needs to be specified.	FoodItem object	No

Properties and Events

For this interface, 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`	CookingMode	An enumeration value representing the preset cooking mode.
`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":"5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
         "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.

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.