Add Custom Voice Interaction to a Smart Home Skill
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.
You can create an Alexa skill that extends the built-in support for certain utterances with your own custom voice interaction model. For example, your skill can take advantage of the built-in support for utterances that turn a device on or off, and you can also support custom utterances like "Alexa, what can this device do?" in the same skill.
- Skill schemas
- How to update or create a skill with multiple models through ASK CLI
- Update the discovery code for your skill
- Test and certify your skill
- Frequently asked questions
To create a skill that supports native smart home and custom utterances, you create a skill that includes multiple models. If you already have a live skill, you can update it with additional models as well. For an overview of skill models, see Understand the Different Skill Models.
You can build a skill that combines more than one model using the Alexa Skills Kit developer console, the Alexa Skills Kit Command Line Interface (ASK CLI) which is a lightweight interface that calls into the Skill Management API (SMAPI), or directly using the Skill Management API (SMAPI).
Before you can publish a skill with combined models, the skill must satisfy the certification requirements for all the models that it contains. For more information, see the certification requirements for the smart home, custom, and video models.
Note that if you combine video and smart home models in your skill, you must start building your new skill with video as the base model. If you are updating an existing video skill, you can only add a smart home model to an existing video skill, we do not support adding video models to an existing smart home skill. We do support adding video and/or smart home models to an existing custom skill.
A skill's functionality is described with a set of JSON schemas. When you create and manage skills with the developer console these schemas are mostly hidden, but when you use the ASK CLI or SMAPI to manage skills, you modify the schemas directly.
To build a skill that combines the smart home, video, and custom models, you need:
See these pages for more information about how to create each of the required schemas. The interaction model schema depends on the work you've done to define a voice interface. For more information, see Design a Voice Interface.
How to update or create a skill with multiple models through ASK CLI
For more information about how to update or create a skill with multiple models through ASK CLI, see Add Custom Voice Interaction to a Smart Home Skill Using ASK CLI.
Update the discovery code for your skill
When you combine smart home and custom skill features, you must update your skill's Lambda function code. Modify your smart home discovery response for device endpoints that support custom features to include an Alexa.CustomIntent capability. Use the configuration object of this capability to describe one or more custom intents defined in the voice model for your skill that can control the device defined in the discovery response. By doing this, Alexa can associate the custom intent with that device, which helps when a customer invokes those intents as they would for a native smart home request.
Test and certify your skill
You can perform most of the functions provided in the Alexa Skills Kit developer console through ASK CLI. For more information about ASK CLI, see Quick Start Alexa Skills Kit Command Line Interface (ASK CLI).
To see all of the available high-level commands, enter:
To see all the available low-level commands through the Skill Management API, enter:
ask api --help
For more information about these commands, see ASK CLI Command Reference.
Frequently asked questions
1. I have a smart home skill live with many customers who have enabled it. If I add custom capabilities to it, will my existing customers be able to use them?
Yes, the existing customers will be able to use the new capabilities without doing anything if the following are true:
- There is no change needed in the account linking process (authorization URL, scope, domains, and so forth) for the custom features to function.
- The tokens exchanged during smart home skill enablement work with your custom functionality.
Otherwise the customers will have to perform account linking again.
2. I have a custom skill live with many customers who have enabled it. If I add smart home to it, will my existing customers be able to use them?
Yes, the existing customers will be able to use the smart home capabilities without doing anything if the following are true:
- They have already done account linking for the custom skill.
- There is no change needed in the account linking process (authorization URL, scope, domains, and so forth) for the smart home features to function.
If the customers never did account linking for the custom skill, you must notify your customers that they have to do the account linking for the smart home features to function.
Note that smart home requires Auth Code Grant type authentication, if your custom skill supports Implicit Grant type then it will need to be migrated prior to adding smart home.
3. How are shared attributes or validations addressed across the skill APIs?
When there is a shared attribute or validation, the stricter rule applies to the skill. For example, smart home skills require account linking, so if you include smart home capability in your skill, then account linking becomes mandatory for enablement regardless of other capabilities added to the skill.
4. Can I specify different endpoints for each skill API and handling custom models?
Yes, you have the option to handle all requests for the skill in the same endpoint or use different endpoints for smart home and custom capabilities, if desired. Even if the endpoint is the same, you need to specify the endpoint for both the smart home and custom model in the skill manifest.
5. Where can I view metrics for my skills?
You can view the metrics for skills created using Skill Management API on the Alexa Skills Kit developer console. You can select each of the capabilities to view metrics for it separately.
6. What is the certification process for a skill built using multiple APIs?
All skills need to be submitted for certification. After you update your skill, you must resubmit it for certification. The certification process is the same for all skills, but the requirements for certification can vary depending on the API or model used. The skill must pass all the certification requirements for all the capabilities before it can be published. For example, a skill that combines smart home and custom models must pass the test cases for both. For more information, see the certification requirements for the smart home, custom, and video models.
7. How many sample phrases will be shown on my skill's detail page?
There is no change in the number of sample phrases allowed. Currently, only three sample phrases will be shown on the detail page.
8. Can I remove a model from my published skill?
No, this is not currently supported. However, you can create a new skill which is a copy of the existing skill but with the desired model removed. You must then publish your new skill and notify your customers to enable and use it.