Vielen Dank für deinen Besuch. Diese Seite ist nur in Englisch verfügbar.

Alexa.Cooking.PresetController Interface

The Alexa.Cooking.PresetController describes the messages used to control cooking appliances that can cook with custom settings. This interface must be used with the Alexa.Cooking interface.

For information about skills and additional interfaces related to cooking, see Build Smart Home Skills for Cooking Appliances.

Preset catalogs

Preset cooking relies on a catalog that you provide to us. Catalogs can vary by brand, appliance type, and model. You identify the catalog to use when you provide discovery for an appliance, and items from that catalog are sent in directives to your skill. To submit a preset cooking catalog for Alexa to use, complete the following steps.

  • Send email to alexa-kitchen-presets@amazon.com. In the subject line provide:

    • Appliance brand
    • Appliance type
    • Appliance model

    Example email request:

    To: alexa-kitchen-presets@amazon.com
    Subject: Brand: some appliance brand, Appliance type: some appliance type, Appliance model: some appliance model

  • You will receive a response within two weeks with:

    • Details of how to format your preset information in Excel and where to upload the Excel file that contains your preset catalog.
    • A preset catalog ID, which is a unique identifier for this catalog. The ID is between 3 and 63 characters long, and contains only numbers, lower case letters, and hyphens. You specify this value in a discovery response for the appliance.

Discovery

In addition to the standard discovery format, the PresetController discovery response should include a configuration object with the following fields.

Configuration object

Property Description Type Required
presetCatalogId The identifier for the preset catalog to use for this controller. See Preset catalogs String Yes
supportedCookingModes Specifies the cooking modes supported for this appliance's implementation of the PresetController interface. Cannot be empty or contain OFF. The default cooking mode, which is used when the customer does not request a cooking mode, is the first cooking mode in the array. An array of CookingMode Values. Yes
supportsRemoteStart True indicates the appliance starts with an Alexa voice command. 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

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "abc-123-def-456"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "appliance-001",
                "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.PresetController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "presetName"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "presetCatalogId": "microwave-001-catalog",
                            "supportedCookingModes": ["DEFROST", "REHEAT"],
                            "supportsRemoteStart": true
                        }
                    }
                ]
            }]
        }
    }
}

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.

CookByPreset

Represents a request to start cooking using a preset option offered by the cooking appliance. Alexa interprets the food and cooking verb from the user to send a CookByPreset directive.

User: Alexa, microwave the popcorn
User: Alexa, cook the pizza in the microwave
User: Alexa, cook chocolate chip cookies in the oven

Example Request

User: Alexa, cook pizza in the microwave

{
    "directive": {
        "header": {
            "namespace": "Alexa.Cooking.PresetController",
            "name": "CookByPreset",
            "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": {
            "presetName": "pizza",
            "foodItem": {
                "foodName": "pizza",
                "foodCategory": "PIZZA"
            },
            "cookingMode":"PRESET"
        }
    }
}

Payload details

Field Description Type Required
presetName Indicates the name of the preset cooking option, for example, popcorn or frozen dinner. You can customize this list by submitting a list of preset options supported by your endpoints to Amazon. See Preset catalogs String Yes
cookingMode The cooking mode specified by the user, such as REHEAT. If not specified by the user, Alexa sends the default cooking mode specified in endpoint discovery. A CookingMode Object or a CookingMode String. Yes
foodItem The type of food to cook, if it was specified. FoodItem object No

Additional Examples

Defrost an item

User: Alexa, defrost five pounds of chicken breast

Alexa sends a CookByPreset directive

The directive indicates:

  • preset is chicken breast
  • cookingMode set to defrost
{
    "directive": {
        "header": {
            "namespace": "Alexa.Cooking.PresetController",
            "name": "CookByPreset",
            "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": {
            "presetName": "chicken",
            "foodItem": {
                "foodName": "chicken breast",
                "foodCategory": "CHICKEN",
                "foodQuantity": {
                    "@type": "Weight",
                    "value": "5",
                    "unit": "POUND"
                }
             },
            "cookingMode": "DEFROST"
        }
    }
}

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
presetName String An enumeration value representing the preset cooking mode. See Preset catalogs for more information.

Response

If the CookByPreset directive was successfully handled, you must respond synchronously with a Response event.

Example Response

{
   "context":{
      "properties":[
         {
            "namespace":"Alexa.Cooking",
            "name":"cookingMode",
            "value":"PRESET",
            "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":"isHolding",
            "value":false,
            "timeOfSample":"2017-08-31T23:30:00Z",
            "uncertaintyInMilliseconds":0
         },
         {
            "namespace":"Alexa.Cooking",
            "name":"foodItem",
            "value":{
               "foodName":"sockeye salmon fillet",
               "foodCategory":"FISH",
               "foodQuantity":{
                  "@type":"Weight",
                  "value":"2.5",
                  "unit":"POUND"
               }
            },
            "timeOfSample":"2017-08-31T23:30:00Z",
            "uncertaintyInMilliseconds":0
         },
         {
            "namespace":"Alexa.Cooking.PresetController",
            "name":"presetName",
            "value":"Salmon",
            "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.

Interface Description
Alexa.Cooking Provides directives for cooking when no preset option is available.
Alexa.Cooking.TimeController Provides directives for cooking by time interval.
Alexa.TimeHoldController Provides directives for pausing or resuming an endpoint.