Grato por sua visita. Neste momento esta página está apenas disponível em inglês.

Alexa.CustomIntent Interface

Preview

The features described on this page are available in preview.

To learn more, see the announcement on the Alexa Blog.

To request access to these features in preview, fill out this survey.

The Alexa.CustomIntent interface enables you to use the smart home skill discovery process to associate custom intents with device endpoints. You can use this interface to describe endpoints that:

  • Support both smart home and custom voice interactions
  • Support custom voice interactions only, but you wish to associate it with your smart home skill that controls additional smart home endpoints

The Alexa.CustomIntent interface defines discovery response configuration only and does not define directives, events or properties.

For the list of locales that are supported for the CustomIntent interface, see List of Capability Interfaces and Supported Locales.

Overview

Alexa uses the configuration you provide for Alexa.CustomIntent to map custom intents to device endpoints reported through the smart home discovery process. When you use the CustomIntent capability, it is easier for Alexa to identify requests that are meant for your skill and are not already defined in the Alexa voice model for smart home endpoints. A customer can then use the intents with that device simply by using the device's friendly name when they make a request. This provides a more seamless and consistent experience for a customer. When you use CustomIntent, it is important that you make sure that the custom intents you identify match intents defined in the custom interaction model for your skill.

For example, if you were to create a smart home skill for a smart vacuum, you might implement the PowerController capability to control turning the device on and off, but also enable Alexa.CustomIntent to control the vacuum mode. For this example, you might name the custom intent ModeIntent. Then, a user could say:

"Alexa, turn on my smart vacuum"

-and-

"Alexa, put my smart vacuum in eco mode"

Alexa would recognize both of these intents and apply them to an endpoint with a friendly name of "smart vacuum". As a result your skill code would receive:

  • A TurnOn directive, which is defined by the PowerController capability, as a result of the request to turn on the vacuum.
  • An IntentRequest that contains an intent object named ModeIntent as a result of the request to put the vacuum in eco mode.

You can configure these messages to be sent to the same or two different service endpoints. You specify these details in the skill manifest. See Add Custom Voice Interaction to a Smart Home Skill Using ASK CLI for more details.

Discovery

When you provide a discovery response for a device that implements Alexa.CustomIntent, you must describe the custom intents that your endpoint implements with a configuration object. The configuration contains an array of supported intents. Make sure the custom intents you specify map to custom intents defined in the voice model for the skill.

Configuration Payload

The CustomIntent discovery response should include a configuration object with the following fields.

Property Description Type Required
supportedIntents Specifies the name of custom intents supported by this endpoint. An array of intent objects that contain a name and value to identify custom intents. Example intent object: {"name": "ModeIntent"}. This array must contain at least one item. Yes, and the array must contain at least one name/value pair.

Example: Discovery with CustomIntent

The following example shows an endpoint that supports the PowerController capability and a custom intent.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "appliance-001",
          "friendlyName": "My Smart Vacuum",
          "description": "Smart vacuum by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "OTHER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.CustomIntent",
              "version": "3",
              "configuration": {
                "supportedIntents": [
                  {
                    "name": "ModeIntent"
                  },
                  {
                    "name": "PauseIntent"
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ]
        }
      ]
    }
  }
}

Directives, Properties and Events

There are no directives, properties or events defined by the capability.

Add Custom Voice Interaction to a Smart Home Skill – This topic describes how to configure skills that combine smart home and custom capabilities.