Steps to Create a Video Skill

You create a video skill in the Amazon developer portal. Once you’ve created the skill, you provide skill information, configuration and skill code hosted as an AWS Lambda function (an Amazon Web Services offering) that handles requests from the Video Skill API and communicates with a device or video streaming service. To enable this communication, the cloud or service should support the OAuth 2.0 authorization code grant type. You will need information about the authentication endpoint, client ID and secret to complete the video skill registration.

This topic provides the steps for creating a skill in the developer portal, creating the AWS Lambda function, configuring and testing your skill, and submitting it for certification.

Register as an Amazon Developer and Create a Skill

To configure a new video skill, you need an account on the Amazon Developer Portal. If you don’t already have an account, go to https://developer.amazon.com/login.html and create an account. Registering is free. Once you’ve registered:

  1. Open the Amazon Developer Portal in a browser and log in.
  2. Navigate to the Alexa section Select Alexa in the top navigation.
  3. In the Alexa Skills Kit box, select Get Started.
  4. Click the Add a New Skill button.
  5. On the Skill Information page, select Video Skill API
  6. Select the language for your skill from the drop-down. You can additional languages later.
  7. Enter the Name for your skill. Note that your skill’s name must not indicate that its functionality is limited. For example, you should not use “basic”, “reduced” or “simple” in the name of your skill.
  8. Click Save.
  9. Note the application Id for your skill as you will use this in the next section.

Create a Lambda Function

You will need an AWS account and some basic knowledge of AWS.

The code for your video skill is hosted as a Lambda function on AWS. AWS Lambda is a service that lets you run code in the cloud without managing servers. The Video Skill API sends your skill requests. Your code parses the request, takes any necessary actions, and responds.

You need an AWS Identity and Access Management (IAM) Role with the AWSLambdaBasicExecutionRole policy attached. If you don’t have this, complete the steps for To create an IAM role before completing the steps to create a Lambda function. If you already have a role with this policy, skip to To create a Lambda function.

To create an IAM role

Navigate to the Identity and Access Management (IAM) console.

  • Choose Roles and click Create a new role.
  • Select AWS Lambda under AWS Service Role.
  • Type “basic” in the filter box and choose the AWSLambdaBasicExecutionRole, and click Next Step.
  • Enter a name that identifies this role and Create role.

To create a Lambda function

  1. Sign in to your AWS account, and click Services
  2. On the AWS Console, under Compute, select Lambda.
  3. Make sure you’ve selected the N.Virginia for English (US) skills or the EU (Ireland) region for English (UK) and German skills. The region is displayed in the upper right corner. Providing your Lambda function in the correct region prevents latency issues.
  4. Click Create a Lambda function.
  5. On the Select blueprint page, Select the Blank Function.
  6. On the Configure triggers page, Click the dashed square to select a trigger. Choose Alexa Smart Home from the displayed list.
  7. Add the Application Id for your skill from the developer portal.
  8. Optionally check Enable trigger. This enables the Amazon Alexa service to call your Lambda function. It’s recommended that you enable the trigger later, once you have completed the implementation and testing of your Lambda function.
  9. Click Next.
  10. On Step 3: Configure function, enter the following:

    • Name: A name for your Lambda function. This name is appears in the AWS console and is also returned by the AWS command-line interface (CLI) ListFunctions API. It should be unique across your Lambda functions.
    • Description: Optionally provide a description.
    • Runtime: Select Python 2.7. Lambda also supports Node.js and Java, but the example you will work with is in Python.
  11. For Lambda function code, make sure Edit code inline is selected.
  12. You can create a Lambda function in Node.js, Java, Python, or C#. This example uses Python. Copy and paste the following Python code into the code editor. This code provides a starting point for implementing a video skill. The code determines the request type by determining the namespace and name values in the message header. The namespace specifies whether the request is a Discovery or ChannelControl request, and either the handleDiscovery or handleChannelControl function is called. For a ChannelControl request, the name property specifies the kind of request. In this example code, the only request type detected is a ChangeChannel. The response is not fully implemented. You should handle every type of request a user would make to your skill, and provide the correct response headers and payload. For information about all of the request and response messages, see the interface reference topics such as Alexa.Discovery or Alexa.PlaybackController.

    def lambda_handler(event,context):
              namespace = event['directive']['header']['namespace']
              if namespace == 'Alexa.Discovery':
                 return handleDiscovery(context,event)
              elif namespace == 'Alexa.ChannelController':
                return handleChannelControl(context,event)
        
    def handleDiscovery(context, event):
             payload = {}
             header = {
                    "messageId": event['directive']['header']['messageId'],
                    "name": "Discover.Response",
                    "namespace": "Alexa.Discovery",
                    "payloadVersion": "3"
             }
       
             if event['directive']['header']['name'] == 'Discover':
                 payload = {
                     "endpoints": [
                         {
                             "capabilities": [
                                 {
                                     "interface": "Alexa.RemoteVideoPlayer",
                                     "type": "AlexaInterface",
                                     "version": "1.0"
                                 },
                                 {
                                     "interface": "Alexa.ChannelController",
                                     "type": "AlexaInterface",
                                     "version": "1.0"
                                 },
                                 {
                                     "interface": "Alexa.PlaybackController",
                                     "version": "1.0",
                                     "type": "AlexaInterface"
                                  }
                             ],
                             "endpointId": "videoDevice-001",
                             "description": "Device description that's shown to the customer",
                             "displayCategories": [],
                             "friendlyName": "Upstairs Amazon Player",
                             "manufacturerName": "Amazon"
                         }
                     ]
                 }
             response = {
                 'header': header,
                 'payload': payload
             }
             return {'event': response}
       
    def handleChannelControl(context, event):
             payload = {}
             header = {}
             messageId = event['directive']['header']['messageId']
             if event['directive']['header']['name'] == 'ChangeChannel':
                 header = {
                     "namespace":"Alexa.ChannelController",
                     "name":"ChannelChanged",
                     "payloadVersion":"3",
                   "  messageId": messageId
                 }
             response = {
                 'header': header,
                 'payload': payload
             }
             return { 'event': response }
    
  13. On the Configuration For Handler, for this example, leave the default name lambda_function.lambda_handler. A function handler is the main entry point for a Lambda function, and you specify it with the format fileName.entryPointFunctionName. For this example, the file name is lambda_function and the lambda_handler function is the entry point in this code.
  14. For Role, you attach a role that enables Lambda execution. If needed you should have created one in a previous step. Select Choose an Existing role and find the role in the Existing Role list.
  15. Leave the Tags and Advanced settings as-is and click Next.
  16. On the Review page, you should see something similar to the following:

  17. Click Create function.
  18. On the summary page, copy the Amazon Resource Name (ARN) for your Lambda function, which is found in the upper right corner, into your clipboard. You will use this value to finish configuring the video skill in the developer portal. The ARN should be similar to the following: ARN -arn:aws:lambda:us-east-1:025463977285:function:myVideoFunction

Test the Lambda Function in the AWS Console

  1. If you want to perform a quick test of the Discovery request in the Lambda code editor, you can click on Test and for the Sample event template, leave the default Hello World. Replace the entire contents of the text editor with the following code.

     {
        "directive":{
           "header":{
              "messageId":"12efe1cb-7a9c-4baf-9776-074d9166b5b8",
              "name":"Discover",
              "namespace":"Alexa.Discovery",
              "payloadVersion":"3"
           },
           "payload":{
              "scope":{
                 "type":"BearerToken",
                 "token":"some-access-token"
              }
           }
        }
     }
    
  2. Select Save and test to execute the test. If successful, the Execution result should be similar to the following:

{
  "event": {
    "header": {
      "payloadVersion": "3",
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "messageId": "12efe1cb-7a9c-4baf-9776-074d9166b5b8"
    },
    "payload": {
      "endpoints": [{
        "endpointId": "videoDevice-001",
        "capabilities": [{
            "interface": "Alexa.RemoteVideoPlayer",
            "version": "1.0",
            "type": "AlexaInterface"
          },
          {
            "interface": "Alexa.ChannelController",
            "version": "1.0",
            "type": "AlexaInterface"
          },
          {
            "interface": "Alexa.PlaybackController",
            "version": "1.0",
            "type": "AlexaInterface"
          }
        ],
        "manufacturerName": "Amazon",
        "friendlyName": "Upstairs Amazon Player",
        "displayCategories": [],
        "description": "Device description that's shown to the customer"
      }]
    }
  }
 }

Finish Registering Your Skill in the Developer Portal

To finish registering your skill, you must configure OAuth 2.0 for your skill, which is used for account linking. You can use Login with Amazon or another provider for this section.

  1. Navigate back to your skill in the Developer Portal. To do this, log in, and navigate to the Alexa section clicking Alexa in the top navigation. Select your skill from the displayed list.
  2. You can click past the Interaction Model tab. The interaction model, which is what a user can say to invoke a video skill, is predefined. Each interface topic lists samples of what a user can say to results in a particular directive being sent to your skill.
  3. On the Configuration page, select the language for your skill and post the ARN number you copied into the correct Endpoint field. For example, provide the ARN for a Lambda function in the N Virgina region in the North America text box.
  4. You must enable Account Linking for your skill. This allows end-users to associate their cloud-enabled devices with the Alexa skill. When a user enables and account-links your skill, they will be granted an access token that is then included in each directive from the Video Skill API. To complete this information, you need OAuth 2.0 information for the device cloud or service your skill communicates with. To learn more about account linking, see Linking an Alexa User with a User in Your System. If you haven't implemented OAuth 2.0, you could consider using Login with Amazon (LWA) as your OAuth provider. For a guide to using LWA to provide account linking for an Alexa skill, see 5 Steps to Seamlessly Link Your Alexa Skill with Login with Amazon. It’s important to note that the OAuth provider must have a certificate signed by an Amazon-approved certificate authority or account linking will fail. In addition, access tokens provided by your system must have a lifetime of at least 6 minutes. This means the expires in parameter of your access token response must be greater or equal to 360. The following fields are required:
    • Authorization URL: This is the URL for your web site’s login page. See Adding Account Linking Support to Your Login Page for information.
    • Client ID: Identifies that a request came from this Alexa skill. This value is passed to your authorization URL in the client_id parameter. This value is also part of the client credentials that the Alexa service includes when requesting an access token from the Access Token URI. This field defaults to alexa-skill, but you can provide a different value, particularly if you have multiple Alexa skills.
    • Domain List: Optional. Use to list domains the authorization URL will fetch content from.
    • Scope: Specify one or more scopes that identify the access the user needs for their account in your video service. This value will be passed as a URL parameter in the call to your authorization URL. At least one scope must be provided.
    • Redirect URLs: The URLs your login redirects the user to after they are authenticated. These URLs should be white-listed with your OAuth provider. Each language version of the skill will have a different Redirect URL.
    • Authorization Grant Type: Authorization Code Grant is the only choice that you can select, as it's the supported grant type for video skills. For Authorization Code Grant, you must also fill in the following:
      • Access Token URI: The URL for the OAuth server that provides the access and refresh tokens, and responds to token requests and token refresh requests. Alexa makes calls to this URI with the client credentials you provide and the OAuth server responds with an access token.
      • Client Secret: A credential you provide that lets the Alexa service authenticate with the Access Token URI. This is provided by the OAuth provider. This is combined with the Client Id to identify the request as coming from Alexa
      • Client Authentication Scheme: Identifies the type of authentication Alexa should use when requesting tokens from the Access Token URI.
    • Privacy Policy URL: A URL for a page that contains your privacy policy. This link is displayed in the Alexa app and is required for video skills. The privacy policy content must be on the page specified by the URL, and cannot be delivered via PDF or other downloadable formats.
  5. Click Next.
  6. On the Test page, click Next.

Provide Publishing Information

Before testing your skill, you must provide publishing information. In the developer portal, select your video skill and navigate to the Publishing Information page. The information you provide here displays with your skill in the Alexa app and is required unless noted as optional.

  • Category: This is automatically set to Video and cannot be changed.
  • Test Instructions: You must:

    • Provide valid test account credentials (username and password) for your skill so the certification team can complete account linking.
    • Make sure the the device cloud for this test account contains at least one discoverable device for testing purposes.
    • Provide any additional instructions necessary to test your skill.
  • Countries & Regions: Select the countries where you skill is supported. Not that your skill must be offered in the primary language of the countries you choose.
  • Short Skill Description: Displays in the skill list
  • Full Skill Descriptions: Provide prerequisites for customers to use your skill
  • Example Phrases: Provide example phrases that work with your skill.
  • Keywords: (optional) Add keyword appropriate for your skill.
  • Images: Add small and large icons per the guidelines specified.
  • Click Next.

Test Your Skill

When your implementation is complete, and you’ve tested your skill adapter in Lambda, you can functionally test your video skill. You will test your skill with an Alexa-enabled device (such as an Amazon Echo). To do this:

  1. Make sure the device with Alexa (such as an Amazon Echo) is registered to your developer account.
  2. Ensure testing is enabled, by choosing your skill in the developer portal, and on the Test tab, ensure Start Testing your Skill is set to Yes.
  3. Ensure the trigger is enabled for your lambda function. To do this, in the Lambda console, select your video skill, and on the Triggers tab, click Enable to enable the Alexa Smart Home trigger.
  4. Find your skill in the Alexa app and enable and account-link your skill to the device cloud or service it is designed to work with. To find your skill in the Alexa app:
    • Go to Skills, and Your Skills in the upper right corner. Find your skill in the list. If you want to remove account linking later, you should disable your skill in the Skills tab.
    • You will be prompted to associate your skill with a device.
  5. Give Alexa commands using the utterances based on capabilities your skill supports. Make sure and test the skill with valid utterances and invalid ones, and in a variety of conditions, such as with a target device powered off. For a list of utterances and recommended test cases, see the Testing Guide

The test cases provided contain tests very similar to the tests used during skill certification testing. Running these tests and addressing issues before submitting for certification is an important step to get your skill published and available to customers as fast as possible. When issues are found during self-testing, usually they are much easier to fix, and you are more likely to pass certification the first time.

Beta Test Your Skill

You can optionally ask other users to beta test your skill before you submit your skill for certification. In order to do this, you must complete all of the information in Certification section. At this point, the Beta Test Your Skill button will be enabled, and you can complete information to start a beta test. For more information, see Skills Beta Testing.

Submit Your Skill for Certification

The final step is getting your skill certified. Once certified, it appears on the skills tab of the Alexa app and customers can use your skill. To start this process, do the following: In the developer portal, select your video skill and navigate to the Publishing Information page. The information you provide here displays with your skill in the Alexa app.

  • On the Privacy and Compliance page, answer the questions, and click Submit for Certification.

Congratulations! You’ve successfully created and submitted a video skill for certification. You should hear from the certification team in a few days with the status of your skill; whether it’s passed certification or whether there are issues to fix. When your skill passes certification and is available for customers, its status will change to Live in the developer portal.

Submit Changes to a Live Skill

Once your skill Status is Live, any changes to the skill must be certified. For example, your skill must be recertified when you change the skill metadata or the AWS Lambda function. The certification review varies depending on the changes, and updating the Lambda function may cause additional review.

A new Development version is automatically created in the developer portal. This version has the same information as the original live version. You can use it to continue to work on your skill to improve it and add features.

The live and development versions are displayed together in the list of skills in the developer portal. When collapsed, the skill shows the development version:

Published skill with row collapsed
Published skill with row collapsed

If you expand the row, you can see both the development and live versions:

Published skill with row expanded
Published skill with row expanded

When you submit your updated skill to the developer portal, use the Testing Instructions field to provide a change log detailing the changes you made.

Update your Lambda function

Do the following to update your AWS Lambda function:

  1. Create a new lambda function with a new ARN, and copy the code from your live Lambda function into the new Lambda function.
  2. Make your updates in the new Lambda function. Avoid updating the live Lambda function that supports your live skill, and avoid Lambda aliases or versioning because they do not work reliably once your skill is updated.
  3. In the development version of your skill, update the Lambda ARN configuration to point to the new Lambda ARN.

After your skill is recertified and the status is live, your skill points to the new Lambda ARN. You can then deprecate the previous Lambda function or use the function for future development or updates.