Steps to Create a Music or Radio Skill

To create a music or radio skill, you provide information, configuration, and an endpoint for your skill code. Your skill code is an AWS Lambda function (an Amazon Web Services (AWS) offering) that handles requests from the Alexa Music and Radio Skill API and communicates with your music service cloud.

Before you create a music or radio skill, make sure that you've taken care of the prerequisites.

Music providers in the US can create a music skill in the Alexa Skills Kit developer console or with the Alexa Skills Kit Command Line Interface (ASK CLI). For the detailed steps, see create a music skill in the developer console or create a music or radio skill with the ASK CLI.

For radio providers, you can only create your skill using the Alexa Skills Kit Command Line Interface (ASK CLI). For detailed steps, see Create a music or radio skill with the ASK CLI.

Create a music skill in the developer console

The Alexa Skills Kit developer console is a web application for creating and managing skills in a web browser.

To create a music skill in the developer console:

  1. Sign in to the ASK developer console.
  2. Click the Create Skill button.
  3. On the Create a new skill page, do the following:
    1. For Skill name, type a name for your skill. For example, "MyMusicSkill".
    2. For Choose a model to add to your skill, select Music. If you don't see the Music option, see I can't create a music skill in the Alexa Skills Kit developer console on the Troubleshooting page.
    3. In the top right corner of the page, click the Create skill button.
  4. On the left side of the page, click Endpoint.
  5. Copy the skill ID displayed near the top of the page. For example, amzn1.ask.skill.22649d8f-0451-4b4b-9ed9-bfb6c036f905. You need the skill ID later to configure your AWS Lambda function.

To update your skill name, prompt name, or invocation names:

  1. On the left side of the page, click Skill Names.
  2. Type or update your skill name, prompt name, or invocation names. Then click the Save button in the top right corner of the page.

To select the interfaces that your skill supports:

  1. On the left side of the page, click Interfaces.
  2. Select the check boxes next to the interfaces that your music skill supports. Then click the Save button in the top right corner of the page.

To select the features that your skill supports:

  1. On the left side of the page, click Features.
  2. Select the check boxes next to the features that your music skill supports. Then click the Save button in the top right corner of the page.

Explicit Language Filter feature

The Explicit Language Filter (ELF) is a feature for music skills that gives users more control over their listening experience. Users can let Alexa know that they prefer to listen to songs, playlists, and stations without explicit content. When the ELF feature is turned on, Alexa only plays content from skills that support the feature.

To support ELF in a music skill, you need to:

  1. Enable the Explicit Language Filter feature, which tells Alexa that the skill is capable of filtering explicit content. Do this by selecting the Explicit Language Filter check box on the Features page in the ASK developer console, or by adding EXPLICIT_LANGUAGE_FILTER as a feature in your music skill manifest.

  2. Modify your skill code (Lambda function) to handle the ExplicitLanguageAllowed field in Initiate and GetPlayableContent requests by not returning identifiers for explicit content when ExplicitLanguageAllowed is set to false. The ExplicitLanguageAllowed field tells your skill whether the user wants explicit content blocked.

Your skill must filter and not return explicit content when ExplicitLanguageAllowed is false. If you cannot guarantee that your skill can exclude explicit content, disable the Explicit Language Filter feature. When the Explicit Language Filter feature is disabled for a skill, the skill is not available to users who have configured Alexa to block explicit content.

Create a Lambda function

You need an AWS Lambda function for your skill code. First create an IAM role for the Lambda function, then create the Lambda function.

Create an IAM role for Lambda

If you haven't worked with Lambda before, you need to create an Identity and Access Management (IAM) role that enables basic execution. If you already have a role that allows basic execution for Lambda, skip to the next section.

To create an IAM role:

  1. Sign in to the IAM console.
  2. On the left side of the page, click Roles. Then click the Create role button.
  3. Select AWS service. Then, for Choose the service that will use this role, click Lambda. Then click the Next: Permissions button.
  4. In the search box next to Filter policies, type "basic". Select the check box next to AWSLambdaBasicExecutionRole, then click the Next: Review button.
  5. In the box next to Role name, type a name for the role. For example, "LambdaRoleForAlexaSkill". Then click the Create role button.

Create the Lambda function

You use AWS Lambda to host the skill code for your skill. AWS Lambda is a web service that lets you run code in the cloud without managing servers. The Alexa Music and Radio Skill API sends requests to your skill code. Your code inspects the request, takes any necessary actions, then sends back a response.

To create a Lambda function:

  1. Sign in to the AWS Lambda console.
  2. Look in the top right corner of the page to make sure the US East (N. Virginia) region is selected. Currently music skills are supported only in the US.
  3. Click the Create function button.
  4. Select Author from scratch, then do the following:
    1. For Name, type a name for your Lambda function. For example, "MySkillLambda".
    2. For Runtime, choose the programming language or environment that you prefer for your skill code.
    3. For Role, select Choose an existing role. For Existing role, choose the role that you created previously.
    4. Click the Create function button.
  5. On the left side of the page, for Add triggers, choose Alexa Skills Kit.
  6. At the bottom of the page, for Skill ID verification, select Enable (recommended). For Skill ID, paste the skill ID that you copied from the developer console.
  7. At the bottom of the page, click the Add button. Then, at the top of the page, click the Save button.

After you create your Lambda function, copy the ARN displayed near the top of the page. For example, arn:aws:lambda:us-east-1:111122223333:function:MySkillLambda.

If you already created your music skill using the ASK developer console, complete the following steps to add this ARN to the configuration of your music skill. Otherwise, add this ARN to the music skill manifest to create a music skill with the ASK CLI.

To add the Lambda ARN to your music skill configuration:

  1. Sign in to the ASK developer console.
  2. Click on the name of your music skill.
  3. On the left side of the page, click Endpoint.
  4. In the box next to Default endpoint, paste the Lambda ARN. Then click the Save button.

Add your music or radio skill code to the Lambda function

After you create the Lambda function and add it to your skill's configuration, you need to add your skill code to the Lambda function. You can do this in the AWS Lambda console. For more information, see creating functions using the AWS Lambda console editor in the AWS Lambda documentation.

Create a music or radio skill with the ASK CLI

The Alexa Skills Kit Command Line Interface (ASK CLI) is a tool you can use to create and manage skills from the command line. The ASK CLI is a command line client for the Skill Management API (SMAPI).

To install the ASK CLI, complete steps 1 through 3 on the Quick Start ASK CLI page. To see a video demonstrating how to use the ASK CLI, see ASK CLI Setup on YouTube. Before you use the ASK CLI, you should also familiarize yourself with the ASK CLI commands that are not supported for music skills.

To create a music skill using the ASK CLI, first create a Lambda function for your skill's code and know the ARN of the Lambda function. Then use the following command, replacing music-skill.json with the name of a file that contains a valid music skill manifest. For an example music skill manifest, see the example music skill manifest.

ask api create-skill -f music-skill.json

See the following example:

C:\> ask api create-skill -f music-skill.json
Create skill request submitted.
Skill ID: amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4
Please use the following command to track the skill status:
    ask api get-skill-status -s amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4

C:\> ask api get-skill-status -s amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4
{
  "manifest": {
    "eTag": "fbcc6fe0491166550b11a819d55b106e",
    "lastUpdateRequest": {
      "status": "SUCCEEDED"
    }
  }
}

After you create a skill, copy the skill ID (for example, amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4). Then add a trigger for your Lambda function using this skill ID.

To create a trigger for your Lambda function:

  1. Sign in to the AWS Lambda console.
  2. Find the Lambda function for your music skill, then click on it.
  3. On the left side of the page, for Add triggers, choose Alexa Skills Kit.
  4. At the bottom of the page, for Skill ID verification, select Enable (recommended). For Skill ID, paste the skill ID.
  5. At the bottom of the page, click the Add button. Then, at the top of the page, click the Save button.

Create your local project directory

After you create a skill with the preceding command, use the following ASK CLI command to create a local project directory for the skill. Before you use this command, make sure that your skill name is unique among your skills, because the name is used to create (or overwrite) the local project directory. In the following command, replace amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4 with your actual skill ID.

ask clone -s amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4

Configure music and radio skill properties

To configure the properties of your music or radio skill, edit the skill.json file in your local project directory. For more information about music skill properties, see the music skill property reference.

After you edit the skill.json file, update your skill with the ask deploy command. You must use this command from within your local project directory.

The ask deploy command updates your skill in the Alexa Skills Kit developer console, but does not update your live (published) skill. To promote changes from the skill in the developer console to your published skill, you must submit your skill for certification in one of the following ways:

  • Use the ask api submit command in the ASK CLI.
  • Use the Alexa Skills Kit Developer Console:
    1. Sign in to the developer console.
    2. Click on the name of your music skill.
    3. At the top of the page, click the Certification tab.
    4. On the left side of the page, click Submission. Then click the Submit for review button.

Example music and radio skill manifest

The following example shows a valid music and radio skill manifest. To use this example, change the skill name before creating your skill.

This example shows only the music section of the skill manifest. For a complete reference of all properties in a skill manifest, see the skill manifest documentation.

{
  "manifest": {
    "publishingInformation": {
      "locales": {
        "en-US": {
          "summary": "one sentence description of skill",
          "examplePhrases": [
            "play music on <skill name>"
            "<another example phrase>"
          ],
          "keywords": [],
          "name": "display name of skill",
          "description": "longer description of skill"
        }
      },
      "isAvailableWorldwide": false,
      "testingInstructions": "",
      "category": "STREAMING_SERVICE",
      "distributionCountries": [
        "US"
      ]
    },
    "events": {
      "subscriptions": [
        {
          "eventName": "SKILL_ENABLED"
        },
        {
          "eventName": "SKILL_DISABLED"
        },
        {
          "eventName": "SKILL_ACCOUNT_LINKED"
        },
        {
          "eventName": "AUDIO_ITEM_PLAYBACK_STARTED"
        },
        {
          "eventName": "AUDIO_ITEM_PLAYBACK_FINISHED"
        },
        {
          "eventName": "AUDIO_ITEM_PLAYBACK_STOPPED"
        },
        {
          "eventName": "AUDIO_ITEM_PLAYBACK_FAILED"
        }
      ],
      "endpoint": {
        "uri": "<your Lambda ARN>"
      },
      "regions": {
        "NA": {
          "endpoint": {
            "uri": ""
          }
        }
      }
    },
    "apis": {
      "music": {
        "endpoint": {
          "uri": "<your Lambda ARN>"
        },
        "locales": {
          "en-US": {
            "features": [
              {
                "name": "EXPLICIT_LANGUAGE_FILTER"
              }
            ],
            "aliases": [
              {
                "name": "<a name users speak to invoke my skill>"
              }
            ],
            "promptName": "<the name Alexa will speak when referring to my skill>"
          }
        },
        "interfaces": [
          {
            "namespace": "Alexa.Audio.PlayQueue",
            "requests": [
              {
                "name": "GetNextItem"
              },
              {
                "name": "GetPreviousItem"
              }
            ],
            "version": "1.0"
          },
          {
            "namespace": "Alexa.Media.Playback",
            "requests": [
              {
                "name": "Initiate"
              }
            ],
            "version": "1.0"
          },
          {
            "namespace": "Alexa.Media.PlayQueue",
            "requests": [
              {
                "name": "GetItem"
              },
              {
                "name": "SetShuffle"
              },
              {
                "name": "SetLoop"
              }
            ],
            "version": "1.0"
          },
          {
            "namespace": "Alexa.Media.Search",
            "requests": [
              {
                "name": "GetPlayableContent"
              }
            ],
            "version": "1.0"
          }
        ],
        "protocolVersion": "1"
      }
    },
    "manifestVersion": "1.0",
    "permissions": [],
    "privacyAndCompliance": {
      "allowsPurchases": false,
      "isExportCompliant": true,
      "containsAds": false,
      "isChildDirected": false,
      "usesPersonalInfo": false
    }
  }
}

Music and radio skill property reference

This section describes the properties that are specific to music and radio skills. These properties are specified in the music section of the skill manifest, as shown in the previous example. For a complete reference of all properties in a skill manifest, see the skill manifest documentation.

Field Description Required Type
music.endpoint.uri Contains the Amazon Resource Name (ARN) for the AWS Lambda function that contains your music skill code. yes string
music.locales.aliases A list of one, two, or three names that a user can use to invoke your skill. This is similar to the skill invocation name for custom skills, but music skills allow up to three names. For example, if you set "awesome music" as an alias for your skill, users who want to hear top hits from your skill could say "Alexa, play top hits from awesome music" to invoke your skill.

Note that existing users of your skill must disable and then re-enable your skill for alias changes to take effect. For example, if you set your skill alias to "awesome music", any user who enables your skill can interact with your skill through utterances such as "Alexa, play Lady Gaga on awesome music". If you later replace the alias "awesome music" with "best music", current skill users must disable and then re-enable the skill for "Alexa, play Lady Gaga on best music" to work.		 yes list of strings
music.locales.promptName The name that Alexa uses when speaking the name of your skill to users. yes string
music.interfaces A list of music skill interfaces that your skill supports. For more information, see the music skill API reference. yes list of strings
music.locales.features Indicates whether your skill supports the feature to filter explicit language. If it does, include this property with a value of EXPLICIT_LANGUAGE_FILTER. Otherwise, omit this property. no string

ASK CLI commands that are not supported for music or radio skills

The following ASK CLI commands and features are not supported for music or radio skills.

ask new
The ask new command creates a custom skill, not a music skill. For the ASK CLI command to create a music skill, see create a music skill.
ask simulate
This feature is not supported for music skills.
ask add and ask remove
These commands refer to in-skill products which are not supported for music skills.
ask api subcommands
The following API sub-commands are not supported for music skills.
  • get-model
  • head-model
  • update-model
  • simulate-skill
  • get-simulation
  • invoke-skill
  • create-isp
  • update-isp
  • associate-isp
  • disassociate-isp
  • get-isp
  • list-isp-for-skill
  • reset-isp-entitlement
  • delete-isp
  • intent-requests-history

Configure account linking (optional)

Account linking connects the identity or data of the skill user with a user identity in your music service cloud. Account linking is not required.

To learn more about account linking, see understand account linking.

To configure account linking for your skill using the ASK CLI, see the create-account-linking subcommand in the ASK CLI command reference.

Account linking properties are maintained separately from the skill manifest. For more information, see account linking schemas.

Enable your music and radio skill

While you're building your skill, you can enable (or disable) it in the Alexa Skills Kit developer console:

  1. Sign in to the ASK developer console.
  2. Click on the name of your music skill.
  3. At the top of the page, click Test.

  4. On the test page, click the toggle next to Test is disabled for this skill.

    To disable a skill, click the toggle next to Test is enabled for this skill.

You can use the Test page in the developer console to test your skill.

Test your skill

After your implementation is complete and you've tested your skill code in Lambda, you can functionally test your music skill with an Alexa-enabled device. To do this:

  1. Find your skill in the Alexa app, then enable and account-link (if needed) your skill.
  2. Give Alexa commands using the utterances that your skill supports. Make sure to test the skill with valid utterances and invalid ones, and in a variety of conditions, such as with the skill enabled, disabled, not account linked, etc.
  3. When you are satisfied with your skill's performance, you can submit it for certification.

For more details about how to test your skill, see the testing guide.

Submit your skill for certification

The final step is submitting your skill for certification. You can submit your skill for certification on the Certification page in the ASK developer console. After your skill is certified and published, it appears in the Alexa Skills Store for Alexa users to discover.

Submit changes to a live skill

After your skill is live, any changes to the skill must be certified. For example, your skill must be recertified after changing the skill metadata. The certification review varies depending on the changes.

Note that updating your skill's catalog data does not require re-certification. Music skill catalogs are managed separately, with different workflows, compared to skill properties. For more information about catalogs, see upload catalogs.

For more information about the different skill statuses (Live, In Development, etc.) and how to continue working on a skill after it's published, see publication status and revise and update your skill after publication.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment