Steps to Build a List Skill

You can create a list skill when you choose the custom voice interaction model, or you can create a list skill without an interaction model. You update the skill manifest to include the appropriate settings to enable list and skill events.

If you enable list and skill events, you must manage your skill through the Alexa Skills Kit (ASK) Command Line Interface (CLI) and the skill is no longer available to edit in the Alexa developer console.

Follow the steps to build a list skill that synchronizes list events. If your skill is a custom skill that doesn't use events, you can manage it through the Alexa developer console. To add lists to custom skills, see Access the Alexa Shopping and To-Do Lists.

Prerequisites

Before you develop a list skill, make sure that you have the following items:

  • An Amazon developer account. You can use an existing Amazon account to sign in, or you can create a new Amazon developer account. The account is free.
  • An Alexa-enabled device, such as an Amazon Echo. Make sure that you sign in to the Echo with the same credentials as your Alexa developer account.
  • The Amazon Alexa app on your mobile device. For instructions about how to download the Alexa app, see Download the Alexa app on the Amazon website. Make sure that you sign in to the Alexa app on your mobile device with the same credentials as your Alexa developer account.
  • Follow the ASK CLI Quick Start to install the ASK CLI.
  • Create your skill by using the CLI. For details about creating a skill with the CLI, see Create a new skill project.

Steps to add list management capabilities

Complete the following steps to add list management capabilities to your list skill.

  1. Configure permissions to access customer lists.
  2. Handling missing permissions.
  3. Get access to the customer's Alexa lists.
  4. Use list and skill events in your list skill.

Step 1: Configure permissions to access customer lists

Edit the skill manifest to set the appropriate permissions to access the customer's Alexa lists. To support the features of your skill, read or write permissions, or both.

To set up permission for list access in the developer console

  1. Open the skill.json file in your editor.
  2. To subscribe to List events, add the householdList in the apis object.
    Your skill manifest can be either a skill manifest with householdList in the apis object, or a custom skill manifest with an additional householdList field in the apis object. For details, see the sample list skill manifest.
  3. Set up your skill to prompt the customer to grant the appropriate permissions for lists. Include a permissions object. The permissions object enables the skill to ask the customer for read or write permissions to the Alexa lists.
    The list permissions are alexa::household:lists:read and alexa::household:lists:write for read and write respectively. This step achieves the same result as if you set up permissions in the developer portal. The following example shows a permissions object that enables the skill to ask for read and write access to lists:
    "permissions": [{
        "name": "alexa::household:lists:read"
    },
    {
        "name": "alexa::household:lists:write"
    }
    ]
    
  4. If you want to use events, include an events object to describe your subscription to events. Include only those events required by your skill.
    For an example manifest for a list skill with no custom component, see List Skill Manifest.
    If your skill manifest includes an events object and it doesn't include custom in the apis object, a custom interaction model is optional.
  5. Update the manifest for a skill by using the update-skill-manifest CLI command.

After the customer enables the skill, the customer receives cards in the Alexa app that allow the customer to grant or refuse permissions.

Step 2: Handle missing permissions

To access the customer's Alexa lists, the customer must grants permissions to a skill in the Skills section of the Alexa app. Your skill has access until the customer revokes permissions. At any time, the customer can change the allowed access for that skill in Manage Settings on the skill's page in the Alexa app.

If the customer hasn't granted your skill access to their Alexa lists, you must handle this case gracefully. As a best practice, provide a voice prompt and display a permissions card in the Alexa app that explains to the customer to grant the required access in the Alexa app.

The following example code shows a card format for write permissions to a customer's Alexa lists.

{
  "version": "1.0",
  "response": {
    "card": {
      "type": "AskForPermissionsConsent",
      "permissions": [
        "alexa::household:lists:read",
        "alexa::household:lists:write"
      ]
    }
  }
}

Step 3: Get access to the customer's Alexa lists

Implement account linking to associate customers who enabled your skill with their identity in your system. Your skill manifest must include an account linking object, which you can add to the manifest with the update-account-linking subcommand. For details about account linking, see Understand Account Linking. To perform account linking, your skill requires the SkillId, ClientId and ClientSecret.

To obtain skill credentials in the Alexa developer console

  1. Sign in to the Alexa developer console.
  2. From the skill list, locate your custom skill, and then, under the skill name, click Copy Skill ID.
  3. In the dropdown under ACTIONS, select Edit.
  4. Click Build > Tools > Permissions.
  5. To view the ClientId and ClientSecret, scroll to the bottom of the screen, and then click SHOW.
  6. Copy the ClientId and ClientSecret.

Or, you can get the credentials by using one the ASK CLI get-skill-credentials SMAPI subcommand: ask smapi get-skill-credentials -s {skill-id}

Step 4: Use list and skill events in your list skill

Use list events and skill events to create a skill that can respond immediately to the customer's top-level utterances, such as "Alexa, add bananas to my shopping list," even if the customer isn't in a session with the skill. For example, the customer might be listening to the news or playing a game, when the customer adds an item to their Alexa lists.

In the skill service, implement handlers to respond to list events.

Use the Skill Messaging API to access lists when the customer is out of the skill session, such as in your app or website. For details, see Skill Messaging API Reference. If you want your skill to have additional functionality besides syncing lists, add an intent model to your skill. If you also want your skill to include a custom component, it requires a custom interaction model, and you must include a custom object nested in the apis object, as shown in the Custom Skill Manifest example.

Sample code