Steps to Build a Music, Radio, or Podcast Skill

Note: Sign in to the developer console to build or publish your skill.

Important: Anyone can build a music skill for public distribution in the United States. However, radio and podcast skills are currently in developer preview. To register your radio or podcast skill for the preview, contact your Alexa Music, Radio, or Podcast representative.

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

Music and podcast providers can create a new skill in the developer console or with the Alexa Skills Kit Command Line Interface (ASK CLI). For details, see Create a new skill in the developer console or Create a new skill with the ASK CLI.

With just their streaming URL and other station metadata, radio providers can follow a no-code process to make their stations available to Alexa. To learn more and get started, use your Amazon developer account to sign in to the Radio Skills Kit (RSK) console. Radio providers can also use the ASK CLI to create a skill. For details, see Create a new skill with the ASK CLI, and contact your Alexa Music representative.

Note: To access to the RSK console, you must have an Amazon developer account. For details, see Create Your Amazon Developer Account.

Prerequisites

Before you build a music, radio, or podcast 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 Amazon Web Services (AWS) account. As part of its free tier of services, AWS gives you access to resources such as the AWS Lambda that hosts your skill code.
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, 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.

Steps to build a music, radio, or podcast skill

To build a music, radio, or podcast skill, complete the following steps:

Create a skill in the developer console.
Create a Lambda function.
Implement required features in your Lambda function.
Include optional features in your skill.
Upload catalogs.
Enable the skill for testing.
Test the skill in the Alexa app.
Provide publishing information.
Submit the skill for certification.

Step 1: Create a skill in the developer console

You can create a new music or podcast skill in the Alexa Skills Kit developer console. To create a music, radio, or podcast skill with the Alexa Skills Kit (ASK) Command Line Interface (CLI), see Create a new skill with the ASK CLI.

To create a new skill in the developer console

Sign in to the Alexa developer console.
Click Create Skill.
Under Name, Locale, enter the skill name and default language, and then click Next.
- Skill name: This is the name customers will see when you publish the skill. You can edit this name later on the Distribution page.
- Primary locale: You can add additional languages to the skill later.
Under Experience, Model, Hosting service > Choose a type of experience, select Music & Audio.
Under Choose a model, select Music, and then click Next.
Under Review, check your selections. To make a change, click the prior step. Otherwise, click Create skill.
In the left pane, click Endpoint.
Copy the skill ID displayed near the top of the page. For example, amzn1.ask.skill.22649d8f-0451-4b4b-9ed9-bfb6c036f905.
In a convenient place, such as Notepad on Windows or TextEdit on Mac, paste the Alexa Client Id and Alexa Client Secret values, and then save the file. You need the skill ID to configure your AWS Lambda function.

To enter your skill name, prompt name, or invocation names

In the left pane, click Skill Names.
Enter your public skill name, prompt name, and invocation name.
In the top right corner of the page, click Save.

To select the interfaces that your skill supports

In the left pane, click Interfaces.
For each interface that your skill supports, select the check box.
In the top right corner of the page, click Save.

To select the features that your skill supports

In the left pane, click Features.
For each feature that your skill supports, select the check box. For details about the explicit language filter (ELF), see ELF feature.
In the top right corner of the page, click Save.

Step 2: 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

Sign in to the IAM console.
On the left side of the page, click Roles. Then click the Create role button.
Select AWS service. Then, for Choose the service that will use this role, click Lambda. Then click the Next: Permissions button.
In the search box next to Filter policies, enter "basic." Select the check box next to AWSLambdaBasicExecutionRole, then click the Next: Review button.
In the box next to Role name, enter 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, Radio, and Podcast Skill API sends requests to your skill code. Your code inspects the request, takes any necessary actions, and then sends back a response.

To create a Lambda function in the AWS Lambda console

Sign in to the AWS Lambda console.
Look in the top right corner of the page to make sure the US East (N. Virginia) region is selected.
Click the Create function button.
Select Author from scratch, then do the following:
1. For Name, enter 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.
On the left side of the page, for Add triggers, choose Alexa Skills Kit.
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.
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 created your music, radio, or podcast skill in developer console, complete the following steps to add this ARN to the configuration of your skill. Otherwise, add this ARN to the skill manifest. For details, see Create a new skill with the ASK CLI.

To configure the endpoint in the Alexa developer console

Navigate back to your skill in the Alexa developer console.
Under ACTIONS, from the drop-down menu in your skill's row, select Edit.
On the left pane, click Endpoint.
In the box next to Default endpoint, paste the ARN for the Lambda function, and then click SAVE.

Step 3: Implement required features

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

Implement required features for a music skill

To build a music skill, you must implement the following directives:

For the best user experience, your skill should support other directives in addition to those in the preceding list. For example, GetPreviousItem allows users to replay the previous track. The API reference documentation contains additional details about the interfaces and the functionality they provide.

Implement required features for a radio skill

To build a radio skill, you must implement the following directives:

You can optionally implement the GetItem directive.

Implement required features for a podcast skill

To build a podcast skill, see Implement Podcast Skill Features.

Step 4: Include optional features in your skill

You can implement the following optional features in your skill:

Account linking – Use account linking to connect the identity or data of the skill user with a user identity in your music service cloud. Amazon supports account linking in music and podcast skills.
Alexa advertising ID – When you indicate that your skill delivers advertising and you provide a privacy policy, Alexa sends your skill a unique customer advertising ID and the customer preference for receiving interest-based ads in the RequestContext object. Amazon supports Alexa advertising ID in music and radio skills.

Important: To use the advertising ID, your skill must comply with the Alexa Advertising ID Policy Requirements and the Alexa Skill Policy Requirements. Review these requirements before you access the Alexa advertising ID in your skill. For more details, see About Alexa Advertising ID.

Step 5: Upload catalogs

For music and radio skills, see Upload Music or Radio Catalogs.

For podcast skills, see Upload Podcast Catalogs.

Step 6: Enable the skill for testing

Complete the steps to enable your skill for testing in the developer console. Use the Test page in the developer console to test your skill with the Alexa simulator.

Step 7: Test the skill in the Alexa app

After your implementation is complete and you test your skill code in Lambda, you can functionally test your skill with an Alexa-enabled device.

To test your skill in the Alexa app

Find your skill in the Alexa app, and then enable your skill and (if needed) set up account linking.
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, and so on.
When you're satisfied with your skill's performance, you can submit it for certification.

For details, see the testing guide.

Step 8: Provide publishing information

To distribute your skill to the Amazon Alexa Skills Store, you must fill out the required metadata for your skill on the Distribution tab in the developer console. For details about publishing your skill, see Define Skill Store Details and Availability.

Step 9: Submit the skill for certification

When you're ready to publish your skill, submit it for certification. For details, see Test and Submit Your Skill for Certification. After your skill is certified and published, it appears in the Alexa Skills Store for Alexa users to discover.

Explicit language filter feature

The ELF is a feature for music and radio 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 plays content only from skills that support the feature.

Note: ELF isn't supported for podcast skills.

To support ELF in a music skill, you must do the following:

Enable the ELF feature, which tells Alexa that the skill can filter explicit content. Do this by selecting the Explicit Language Filter check box on the Features page in the Alexa developer console, or by adding EXPLICIT_LANGUAGE_FILTER as a feature in your skill manifest.
Modify your skill code (Lambda function) to handle the ExplicitLanguageAllowed field in Initiate and GetPlayableContent requests. The skill must not return identifiers for explicit content when ExplicitLanguageAllowed is set to false.

If you can't guarantee that your skill can exclude explicit content, disable the ELF feature so that the skill isn't available to users who have configured Alexa to block explicit content.

Create a new skill with the ASK CLI

Important: Skip this step if you created a music skill in the console in step 1.

You can use the ASK CLI to create and manage skills from the command line. To create a skill in the developer console instead, see Step 1: Create a new skill.

To install the ASK CLI, complete steps 1 – 3 of the Quick Start ASK CLI page. To see a video that demonstrates how to use the CLI, see ASK CLI Setup on YouTube. Before you use the CLI, you should be familiar with the ASK CLI commands not supported for music, radio, or podcast skills.

To create your skill using the ASK CLI, first create a Lambda function for your skill's code and note 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, radio, or podcast skill manifest. For an example, 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 smapi get-skill-status -s amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4

C:\> ask smapi 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 use this skill ID to add a trigger for your Lambda function.

To create a trigger for your Lambda function:

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

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 smapi export-package -s amzn1.ask.skill.d12647e2-4e5b-4870-9f3c-09a1b88da1a4

Configure your skill properties

To configure the properties of your skill, edit the skill.json file in your local project directory. For details, see the music, radio, and podcast skill property reference.

After you edit the skill.json file, navigate to your local project directory. Then use the ask deploy command to update your skill.

The ask deploy command updates your skill in the Alexa Skills Kit developer console, but doesn't 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.
Test and submit your skill for certification in the developer console.

Example music skill manifest

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

For a complete reference of all properties in a skill manifest, see the skill manifest documentation.

Copied to clipboard.

{
  "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"
          }
        ]
      }
    },
    "manifestVersion": "1.0",
    "permissions": [],
    "privacyAndCompliance": {
      "allowsPurchases": false,
      "isExportCompliant": true,
      "containsAds": false,
      "isChildDirected": false,
      "usesPersonalInfo": false
    }
  }
}

Music, radio, and podcast skill property reference

This section describes the properties that are specific to music, radio, and podcast skills. These properties are specified in the apis.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 skill code.	yes	string
`music.locales.aliases`	A list of one, two, or three names with which a user can invoke your skill. This is similar to the skill invocation name for custom skills, but music, radio, and podcast 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 could say, "Alexa, play top hits from awesome music" to invoke your skill. Existing skill users must disable and then re-enable your skill for alias changes to take effect.	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 skill interfaces that your skill supports. For more details, see the music, radio, and podcast skill API reference.	yes	list of strings
`music.locales.features`	Indicates whether your skill supports the `ELF` feature to filter explicit language. If it does, include this property with a value of `EXPLICIT_LANGUAGE_FILTER`. Otherwise, omit this property. Note that `ELF` isn't supported for podcast skills."	no	string
`music.contentTypes`	(Podcast only) Add this field to use GetPlayableContent for state persistence.	no	object

CLI commands not supported for music, radio, or podcast skills

The following ASK CLI commands and features don't support music, radio, or podcast skills.

ask new: The ask new command can only create a custom skill. For the ASK CLI command to create a music, radio, or podcast skill, see Create a new skill with the ASK CLI.
ask simulate: This feature isn't supported for music, radio, or podcast skills.
ask add and ask remove: These commands refer to in-skill products. In-skill products aren't supported for music, radio, or podcast skills.
ask api subcommands: The following API sub-commands don't support music, radio, or podcast 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

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 needed depends on the type and extent of changes made.

Note that updating your skill's catalog data doesn't require recertification. Skill catalogs are managed separately, with different workflows, compared with skill properties. For more details about catalogs, see upload catalogs.

For details about the different skill statuses, such as Live and In Development, and how to work on a skill after it's published, see publication status and revise and update your skill after publication.

Last updated: Apr 10, 2023