Add Custom Voice Interaction to a Smart Home Skill Using ASK CLI

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 skill manifest is the JSON representation of your skill, and provides Alexa with all of the required metadata. The interaction model and account linking schemas are separate. For an overview, see Add Custom Voice Interaction to a Smart Home Skill.

All images referenced in a skill manifest must be in PNG format.

See also:

 

How to update or create a skill with multiple models through ASK CLI

The following sections explain how to combine existing skills or create a new skill that combines the features of a smart home skill with a custom skill.

Update an existing skill to include smart home and custom features

If you have an existing smart home skill and custom skill that you want to merge, you modify the smart home skill manifest file to include the manifest information from the custom skill. The following steps show how to do this with the ASK CLI.

  1. Install ASK CLI, set up the AWS user account if appropriate, and initialize ASK CLI, as described in Quick Start Alexa Skills Kit Command Line Interface (ASK CLI).

    In the command prompt window, enter:

    ask api list-skills

    All of your skills in your Amazon developer account are listed. Scroll through the list and find the skill ID for the smart home skill you want to modify, and the skill ID for the custom skill you want to add to the smart home skill. Alternatively, you can find these skill IDs in the list of your Alexa skills in the Alexa Skills Kit developer console.

  2. Enter the command to get the skill schemas and direct them to files:

    ask api get-skill -s YOUR_SKILL_ID > my-skill.json

    This command downloads the skill manifest for this skill ID to a file called my-skill.json. You can use the filename of your choice. Repeat for your custom skill, saving the skill manifest to a separate file.

  3. Edit the skill manifest (my-skill.json in this example) to include both the smart home and custom apis entries, as shown in this sample skill manifest.

  4. Upload the modified JSON file, using the skill ID for the smart home skill:

    ask api update-skill -s <skill ID> -f my-skill.json

    The skill manifest is now updated.

  5. You can confirm the update by downloading the skill manifest for this updated skill, with this command:

    ask api get-skill -s YOUR_SKILL_ID > my-skill-multi.json

    You should see the changes you made in the original skill manifest in this new skill manifest file.

Your skill must provide the code to handle the smart home and custom requests, and you must manage the interaction model and account linking schemas for this combined skill. For more information, see Handle Requests Sent by Alexa and Steps to Build a Smart Home Skill.

Create a new skill with smart home and custom features

You can create a new skill that combines smart home and custom features. The following steps show how to do this with the ASK CLI.

  1. From the command prompt window, create a new skill with this command:

    ask new

  2. Enter your new skill name when prompted, such as My-Smart-Home-Custom-Skill.

    A new directory is created with the name of your skill, which contains the files for your skill project.

  3. Edit the skill manifest to include the desired smart home and custom components.

  4. Edit the interaction model and account linking schemas in the skill project files to match what you want for this skill.

  5. Update the skill with this command (using the file name that you used for this skill schema):

    ask api update-skill -s YOUR_SKILL_ID -f my-skill.json

Sample skill manifests

Choose the skill manifest for your skill type. For each skill type, ensure that you consider the privacy and compliance requirements.

If you are creating a skill that combines both a smart home and a custom model, you must provide an ARN (Amazon Resource Name) for each skill type in the endpoint field, and your skill manifest must include all of the objects required for both the smart home and custom portions of the skill. Use only those objects that are required for the skill you are creating.

Combined smart home and custom skill manifest

{
  "manifest": {
    "manifestVersion": "1.0",
    "publishingInformation": {
      "locales": {
        "en-US": {
          "name": "Sample skill name.",
          "summary": "This is a sample Alexa skill.",
          "description": "This skill has basic and advanced smart devices control features.",
          "smallIconUri": "https://smallUri.com",
          "largeIconUri": "https://largeUri.com",
          "examplePhrases": [
            "Alexa, open sample skill.",
            "Alexa, blink kitchen lights."
          ],
          "keywords": [
            "Smart Home",
            "Lights",
            "Smart Devices"
          ]
        }
      },
      "distributionCountries": [
        "US",
        "GB",
        "DE"
      ],
      "isAvailableWorldwide": false,
      "testingInstructions": "1) Say 'Alexa, turn on sample lights'",
      "category": "SMART_HOME"
    },
    "privacyAndCompliance": {
      "allowsPurchases": false,
      "usesPersonalInfo": false,
      "isChildDirected": false,
      "isExportCompliant": true,
      "containsAds": false,
      "locales": {
        "en-US": {
          "privacyPolicyUrl": "http://www.myprivacypolicy.sampleskill.com",
          "termsOfUseUrl": "http://www.termsofuse.sampleskill.com"
        }
      }
    },
    "apis": {
      "smartHome": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:040623927470:function:sampleSkill"
        },
        "regions": {
          "NA": {
            "endpoint": {
              "uri": "arn:aws:lambda:us-west-2:010623927470:function:sampleSkillWest"
            }
          }
        }
      },
      "custom": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:040623927470:function:sampleSkill"
        },
        "regions": {
          "NA": {
            "endpoint": {
              "sslCertificateType": "Trusted",
              "uri": "https://customapi.sampleskill.com"
            }
          }
        }
      }
    }
  }
}

Combined video and custom skill manifest

{
  "manifest": {
    "publishingInformation": {
      "locales": {
        "en-US": {
          "summary": "Sample Short Description",
          "examplePhrases": [
            "Alexa open kitty",
            "Alexa tell kitty I am Jeff",
            "Alexa tell kitty my name is Peter"
          ],
          "name": "kitty",
          "smallIconUri": "https://www.smallIconUri.com/example1.png",
          "description": "Sample Full Description."
        }
      },
      "isAvailableWorldwide": true,
      "testingInstructions": "Sample Testing Instructions.",
      "category": "EDUCATION_AND_REFERENCE",
      "distributionCountries": []
    },
    "apis": {
      "custom": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-west-2:709767356492:function:customWest"
        }
      },
      "video": {
        "locales": {
          "en-US": {
            "videoProviderTargetingNames": [
              "TV provider"
            ],
            "catalogInformation": [
              {
                "sourceId": "1234",
                "type": "FIRE_TV"
              }
            ]
          }
        },
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:452493640596:function:sampleSkill"
        },
        "regions": {
          "NA": {
            "endpoint": {
              "uri": "arn:aws:lambda:us-east-1:452493640596:function:sampleSkill"
            },
            "upchannel": [
              {
                "uri": "arn:aws:sns:us-east-1:291420629295:sampleSkill",
                "type": "SNS"
              }
            ]
          }
        }
      }
    },
    "manifestVersion": "1.0",
    "privacyAndCompliance": {
      "allowsPurchases": false,
      "isExportCompliant": true,
      "isChildDirected": false,
      "usesPersonalInfo": false,
      "containsAds": false
    }
  }
}

Combined video and smart home skill manifest

{
  "manifest": {
    "publishingInformation": {
      "locales": {
        "en-US": {
          "summary": "This is a sample Alexa skill.",
          "examplePhrases": [
            "Alexa, tune to channel 206",
            "Alexa, search for comedy movies",
            "Alexa, pause."
          ],
          "keywords": [
            "Smart Home",
            "Lights",
            "Smart Devices"
          ],
          "name": "SH+Video2",
          "smallIconUri": "https://www.smallIconUri.com/example1.png",
          "largeIconUri": "https://www.largeIconUri.com/example1.png",
          "description": "This skill has basic and advanced smart devices control features."
        }
      },
      "isAvailableWorldwide": false,
      "testingInstructions": "1) Say 'Alexa, discover my devices' 2) Say 'Alexa, turn on sample lights'",
      "category": "SMART_HOME",
      "distributionCountries": [
        "US",
        "GB",
        "DE"
      ]
    },
    "apis": {
      "video": {
        "locales": {
          "en-US": {
            "videoProviderTargetingNames": [
              "hsv TV"
            ],
            "catalogInformation": [
              {
                "sourceId": "1234",
                "type": "FIRE_TV"
              }
            ]
          }
        },
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:452493640596:function:sampleSkill"
        },
        "regions": {
          "NA": {
            "endpoint": {
              "uri": "arn:aws:lambda:us-east-1:452493640596:function:sampleSkill"
            },
            "upchannel": [
              {
                "uri": "arn:aws:sns:us-east-1:291420629295:sampleSkill",
                "type": "SNS"
              }
            ]
          }
        }
      },
      "smartHome": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:032174894474:function:sampleSkill"
        }
      }	  
    },	  
    },
    "manifestVersion": "1.0",
    "privacyAndCompliance": {
      "allowsPurchases": false,
      "locales": {
        "en-US": {
          "termsOfUseUrl": "http://www.termsofuse.sampleskill.com",
          "privacyPolicyUrl": "http://www.myprivacypolicy.sampleskill.com"
        }
      },
      "isExportCompliant": true,
      "isChildDirected": false,
      "usesPersonalInfo": false,
      "containsAds": false
    }
  }
}

publishingInformation object

Field Description Type
locales Object that contains locale objects for each supported locale. Object
distributionCountries Array specifying distribution country/region strings in ISO 3166-1 alpha-2 format, for example US, GB or DE. This array should only contain values if availableWorldwide is false. string array
isAvailableWorldwide true to indicate the skill is available worldwide; otherwise, false. If false, countries must be listed for distributionCountries. boolean
testingInstructions Indicates any special instructions for testing the skill, such as a test account. string
category Indicates the filter category for the skill in the Alexa App such as NEWS or SMART_HOME. Note that any combination of models that include smart home must use the SMART_HOME category. See Category enumeration. string

publishingInformation.locales object

For each supported locale, include an object with the appropriate locale string. The supported values include en-US, en-GB, and de-DE.

Field Description Type
locale Locale string object

publishingInformation.locales.locale object

Field Description Type
summary Summary description of the skill, which is shown when viewing the list of skills. string
description A full description explaining the skill's core functionality and any prerequisites to using it (such as additional hardware, software, or accounts). For a Flash Briefing skill, you must list the feeds for the skill. string
smallIconUri URL to a small icon for the skill, which is shown in the list of skills. (108x108px) string
largeIconUri URL to a large icon that represents this skill. (512x512px) string
examplePhrases Three example phrases that illustrate how users can invoke your skill. For accuracy, these phrases must come directly from your sample utterances. array of strings
keywords Sample keyword phrases that describe the skill. array of strings

privacyAndCompliance object

Field Description Type
allowsPurchases true to indicate purchases can be made from this skill; otherwise, false. boolean
usesPersonalInfo true to indicate this skill uses customer information, otherwise false. boolean
isChildDirected true to indicate the skill is directed at children under 13, otherwise false. boolean
isExportCompliant true to indicate the skill can be exported to any country/region; otherwise, false. boolean
locales Contains locale objects, which each contain the privacy and terms of use URLs for each supported locale object

When you create or modify a skill using a skill manifest, you must ensure that the customer meets the privacy and compliance requirements and the export compliance requirement. The requirements for the customer are the same as the customer must comply with if creating a skill on the Amazon Developer Portal, as shown on the Privacy and Compliance tab when creating a skill on the portal.

The customer must answer the corresponding questions in order to set the values for the privacyAndCompliance object. If the customer answers Yes, set the value to true, and if the customer answers No, set the value to false. You may not provide default answers or values on behalf of the customer.

FieldCorresponding question from Amazon Developer Portal
allowsPurchases Does this skill allow users to make purchases or spend real money?
usesPersonalInfoDoes this Alexa skill collect users' personal information? This includes anything that can identify the user such as name, email, password, phone number, birthdate, etc.
isChildDirected

Is this skill directed to or does it target children under the age of 13?

Please indicate if this skill is directed to children under the age of 13 (for the United States, as determined under the Children's Online Privacy Protection Act (COPPA)).

Not Sure?

isExportCompliantCheckbox: I certify that this Alexa skill may be imported to and exported from the United States and all other countries and regions in which we operate our program or in which you've authorized sales to end users (without the need for us to obtain any license or clearance or take any other action) and is in full compliance with all applicable laws and regulations governing imports and exports, including those applicable to software that makes use of encryption technology.
containsAdsDoes this skill contain advertising?
privacyPolicyUrlPrivacy Policy URL (Optional) Link to the privacy policy that applies to this skill.
Note: Each locale requires a separate privacy policy URL, if one is provided.
termsOfUse Terms of Use URL (Optional) Link to the terms of use document for this skill.
Note: Each locale requires a separate terms of use URL, if one is provided.

privacyAndCompliance.locales object

For each supported locale, include an object with the appropriate locale string. The supported values include en-US, en-GB, and de-DE.

Field Description Type
locale Locale string object

privacyAndCompliance.locales.locale object

locale can be en-US, en-GB, or de-DE, depending on the locales supported by the skill.

Field Description Type
privacyPolicyUrl URL to the privacy policy for the skill for the locale string
termsOfUseUrl URL to the terms of use for the skill. for the locale string

permissions object

An array of named permissions which the skill can use.

Field Description Type
name

Contains an array of permissions, which may contain some or all of these:

  • alexa::devices:all:address:full:read (read the customer's full address entered from the Alexa app settings)
  • alexa::devices:all:address:country_and_postal_code:read (read the customer's country and postal code entered from the Alexa app settings)
  • alexa::household:lists:read (read the customer's Alexa lists)
  • alexa::household:lists:write (write to the customer's Alexa lists)
array

apis object

Array of api-type objects. Some combinations of api-type objects are not supported.

Field Description Type
api-type Includes custom, smartHome, video enum

apis.custom object

Field Description Type
endpoint Contains the uri field object
regions Contains an array of the supported region objects array
interfaces Contains an array of the supported interfaces array

apis.custom.endpoint object

Field Description Type
uri Amazon Resource Name (ARN) for the skill's custom Lambda function or HTTPS URL string

apis.custom.regions object

An array of region fields.

Field Description Type
region Two-letter code for the geographic region such as NA or EU enum
apis.custom.regions.region object
Field Description Type
endpoint Contains the uri and sslCertificate fields object

apis.custom.regions.region.endpoint object

Field Description Type
uri Amazon Resource Name (ARN) for the skill's custom Lambda function or HTTPS URL string
sslCertificateType The SSL certificate type for the skill's HTTPS endpoint. Can be Trusted or Wildcard. Only valid for HTTPS endpoints, not for AWS Lambda ARN. enum

apis.custom.interfaces object

An array of interfaces supported by the skill.

Field Description Type
type Includes AUDIO_PLAYER, VIDEO_APP, RENDER_TEMPLATE. enum

api.smartHome object

Field Description Type
endpoint Contains the uri field object
regions Contains an array of the supported region objects array
protocolVersion (Optional) Version of the Smart Home API. Default and recommended value is '3'. You may create a skill with version '2' for testing migration to version '3', but a skill submission using version '2' will not be certified. String

apis.smartHome.endpoint object

Field Description Type
uri Amazon Resource Name (ARN) for the skill's smartHome Lambda function or HTTPS URL string

apis.smartHome.regions object

An array of region fields.

Field Description Type
region Two letter code for the geographic region such as NA, UK, or EU enum
apis.smartHome.regions.region object
Field Description Type
endpoint Contains the uri field object

apis.custom.regions.region.endpoint object

Field Description Type
uri Amazon Resource Name (ARN) for the skill's smartHome Lambda function or HTTPS URL string
sslCertificateType The SSL certificate type for the skill's HTTPS endpoint. Can be Trusted or Wildcard. Only valid for HTTPS endpoints, not for AWS Lambda ARN. enum

apis.video object

apis.video.locales object

For each supported locale, include an object with the appropriate locale string. The supported values include en-US, en-GB, and de-DE.

Field Description Type
locale Locale string object
apis.video.locales.locale object
Field Description Type
videoProviderTargetingNames List of names array
apis.video.locales.catalogInformation object
Field Description Type
sourceId String that identifies the source string
type Indicates the type, such as "Fire_TV" string

apis.video.endpoint object

Sets the global default endpoint.

Field Description Type
uri Amazon Resource Name (ARN) for the skill's custom Lambda function or HTTPS URL string

apis.video.regions object

An array of region fields.

Field Description Type
region Two-letter code for the geographic region such as NA or EU enum
apis.video.regions.region object
Field Description Type
endpoint Contains the uri field. object
upchannel The channel through which the partner skill can communicate to Alexa object

apis.video.regions.region.endpoint object

Sets the region-specific endpoint.

Field Description Type
uri Amazon Resource Name (ARN) for the skill's video AWS Lambda function or HTTPS URL string

apis.video.regions.region.upchannel object

Sets the endpoint through which the partner skill can communicate to Alexa.

Field Description Type
type Use "SNS" for this field string
uri SNS Amazon Resource Name (ARN) for video skill through which video partner can send events to Alexa string

Enumerations and Values

Category enumeration

This enumeration provides category values. The category determines how your skill is filtered for display in the Alexa app. Note that for any skill that includes a smart home model, the category enumeration must be SMART_HOME.

Enum Values
ALARMS_AND_CLOCKS 
ASTROLOGY 
BUSINESS_AND_FINANCE 
CALCULATORS 
CALENDARS_AND_REMINDERS 
COMMUNICATION
CONNECTED_CAR 
COOKING_AND_RECIPE 
CURRENCY_GUIDES_AND_CONVERTERS 
DATING 
DELIVERY_AND_TAKEOUT 
DEVICE_TRACKING
EDUCATION_AND_REFERENCE 
EVENT_FINDERS 
EXERCISE_AND_WORKOUT 
FASHION_AND_STYLE 
FLIGHT_FINDERS 
FRIENDS_AND_FAMILY 
GAME_INFO_AND_ACCESSORY 
GAMES
HEALTH_AND_FITNESS 
HOTEL_FINDERS 
KNOWLEDGE_AND_TRIVIA 
MOVIE_AND_TV_KNOWLEDGE_AND_TRIVIA 
MOVIE_INFO_AND_REVIEWS 
MOVIE_SHOWTIMES 
MUSIC_AND_AUDIO_ACCESSORIES
MUSIC_AND_AUDIO_KNOWLEDGE_AND_TRIVIA 
MUSIC_INFO_REVIEWS_AND_RECOGNITION_SERVICE 
NAVIGATION_AND_TRIP_PLANNER 
NEWS 
NOVELTY
ORGANIZERS_AND_ASSISTANTS 
PETS_AND_ANIMAL 
PODCAST 
PUBLIC_TRANSPORTATION 
RELIGION_AND_SPIRITUALITY 
RESTAURANT_BOOKING_INFO_AND_REVIEW 
SCHOOLS 
SCORE_KEEPING 
SELF_IMPROVEMENT 
SHOPPING 
SMART_HOME 
SOCIAL_NETWORKING 
SPORTS_GAMES 
SPORTS_NEWS 
STREAMING_SERVICE 
TAXI_AND_RIDESHARING 
TO_DO_LISTS_AND_NOTES 
TRANSLATORS 
TV_GUIDES
UNIT_CONVERTERS 
WEATHER 
WINE_AND_BEVERAGE 
ZIP_CODE_LOOKUP