GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing developer.amazon.com — Host a Custom Skill as an AWS Lambda Function | Alexa Skills Kit

Alexa Skills Kit

Get Started

Skill Types

Skill Development Process

Skill Developer Reference

Host a Custom Skill as an AWS Lambda Function

The easiest way to build the cloud-based service for a custom Alexa skill is to use AWS Lambda, an Amazon Web Services (AWS) offering that runs your code only when it's needed and scales automatically, so there is no need to provision or continuously run servers. After you upload the code for your Alexa skill to a Lambda function, Lambda does the rest, executing it in response to Alexa voice interactions and automatically managing the compute resources for you.

You can use Alexa-hosted Skills to build your Lambda function in the Alexa developer console. Or, you can store your code and resources yourself.

About Lambda functions and custom skills

Using a Lambda function for your service eliminates some of the complexity around setting up and managing your own endpoint:

You don't need to administer or manage any of the compute resources for your service.
You don't need an SSL certificate.
You don't need to verify that requests are coming from the Alexa service yourself. Access to run your function is controlled by permissions within AWS instead.
AWS Lambda runs your code only when you need it and scales with your usage, so there is no need to provision or continuously run servers.
Alexa encrypts its communications with Lambda utilizing TLS. For details, see AWS Best Practices for Security, Identity, & Compliance.
For most developers, the Lambda free tier is sufficient for the function supporting an Alexa skill. The first one million requests each month are free. Note that the Lambda free tier does not automatically expire, but is available indefinitely.

AWS Lambda supports code written in several languages, including Node.js, Java, and Python. For some languages, you can edit the code in the inline code editor in the AWS Lambda console. For basic testing, you can invoke your function manually by sending it JSON requests in the Lambda console.

For an overview of AWS Lambda, see What Is AWS Lambda?

The Lambda function must handle the requests sent to the skill by Alexa. See:

Lambda functions for custom skills can be hosted in any AWS Lambda region. See Select the optimal region for your AWS Lambda function to help determine the optimal choice for your skill configuration.

Complete the procedures in this section to create a new Lambda function for a custom skill and manage AWS resources yourself. To build your Lambda function for a custom skill in the Alexa developer console, see Create and Manage Alexa-hosted Skills.

If you're using the Smart Home API, you use Lambda to create a skill adapter. For details, see Steps to Build Smart Home Add-ons.

Select the optimal region for your AWS Lambda function

When you create an AWS Lambda function, you are prompted to select a region. In most cases, when you create or modify an AWS Lambda function used by your skill, you should use the commonly recommended region shown in the following table. This choice means you reduce latency between Alexa and your skill service. However, if your skill is using other resources that are hosted in a different region, such as DynamoDB databases, Amazon S3 content, or any external services, it might be best to select the region that is closest to those resources in order to reduce overall latency for your skill, even if that region is different from the recommendation in this table. You can decide whether you should make a tradeoff between the latency for Alexa and your skill service, compared to the latency between your skill service and other hosted resources. Look at the Allowed AWS Lambda Regions to determine which region you want to choose for your AWS Lambda function.

ASK region code	Commonly recommended AWS region code	Commonly recommended AWS region name
NA	us-east-1	US East (N. Virginia)
EU or IN	eu-west-1	EU (Ireland)
FE	us-west-2	US West (Oregon)

Allowed AWS Lambda Regions

The list of allowed AWS Lambda regions is listed below. You can use any of these for your AWS Lambda functions if you determine that is the optimal choice for your skill configuration.

Allowed AWS Lambda regions
US East (Ohio)	EU (Frankfurt)	Asia Pacific (Hong Kong)
US East (N. Virginia)	EU (Ireland)	Asia Pacific (Mumbai)
US West (N. California)	EU (London)	Asia Pacific (Seoul)
US West (Oregon)	EU (Paris)	Asia Pacific (Singapore)
Canada (Central)	EU (Stockholm)	Asia Pacific (Sydney)
South America (Sao Paulo)	Middle East (Bahrain)	Asia Pacific (Tokyo)

Use a template to create your Lambda function

If you are using the Alexa Skills Kit SDK for Node or Python, you can use a template provided in the AWS Serverless App Repository to create your function. This method automatically creates the resources you need for the function to work with Alexa:

The Lambda function itself, with starting sample code from the corresponding GitHub repository. You can use this to experiment with the sample functionality, or replace it with your own code.
The SDK dependencies needed for the code. This eliminates the need to upload the dependencies, such as node_modules, yourself.
The trigger that grants Alexa the necessary invocation permissions for your function.
The role for the function. This defines the AWS resources the function can access.

The serverless app repository lets you find applications to deploy. You can think of the "application" in this context as a template for creating a Lambda function.

You deploy an application to create the resources associated with the application in an AWS CloudFormation stack. After you deploy the function, you can work with your Lambda function normally. You don't need familiararity with CloudFormation to set up your Lambda function this way.

The serverless application repository currently contains applications for the ASK SDK for Node v2 and ASK SDK for Python.

If you don't already have an AWS developer account, go to AWS and create an account first.

Direct links to recommended Alexa samples

Use one of the following links to open the page for an Alexa sample in the serverless app repository. To use one of these, click the link, then follow the directions in Deploy the application to create your function, later:

Node.js — alexa-skills-kit-nodejs-premium-facts-skill
Python—alexa-skills-kit-python36-factskill

Search for an Alexa sample

Alternatively, you can search for Alexa samples in the serverless app repository:

If you do not already have an AWS account, go to AWS and create an account.
Log in to the AWS Management Console and navigate to AWS Lambda.
Click Create function.
Select Browse serverless app repository.
Under Public applications, type Alexa in the search box. Note that the officially provided repos show "Alexa Skills Kit" as the author in the lower left of the card.
Click the name of the app to use. This provides you with a detail page about the app. You can see details about the resources that will be created under “Template”
Follow the directions in Deploy the application to create your function, later.

Deploy the application to create your function

Open the page for the serverless application to deploy. You can either use one of the provided links or search and browse the repository for a sample.
From the Region drop-down list in the upper-right corner of the console, select one of the allowed AWS regions.

To determine which one you should choose, see Select the optimal region for your AWS Lambda function.
In the Application Settings section, optionally modify the following:
- Application name
- SkillDescription
- SkillFunctionName
Note that SkillDescription and SkillFunctionName are not included on all templates.

You can deploy with the same template multiple times, but you must use a unique Application name each time.
Click the Deploy button at the bottom of the page.
Wait for the status of all resources to change to CREATE_COMPLETE
Under Resources, click the link to open the newly created function in the Lambda console.

You can now do any of the following:

View and edit the code for the Lambda function
Connect the Lambda function to your skill
Configure the Alexa Skills Kit triggers
Test a Lambda Function in the console

Configure AWS SAM for Lambda functions

If you use AWS Serverless Application Model (SAM) to define and deploy your Lambda function, configure policies that prevent unintended deletion of the function behind your skill endpoint.

By default, SAM generates a unique function name with a random suffix. This approach allows SAM to seamlessly replace Lambda functions when needed, such as when you change the package type from .zip to a container image. However, when SAM replaces a function, it creates a new randomly-named function and deletes the old function. Deletion of the old function causes an outage for skills that use the old function ARN endpoint.

Adding SAM retention policies prevents deletion of the Lambda function by CloudFormation stack updates. After CloudFormation creates a replacement function, you can update your skill endpoint with the new function ARN in the Alexa developer console. Until then, your skill continues to use the old function.

Alternatively, you can specify a static FunctionName in your SAM template. This configuration keeps your function name and ARN consistent, but prevents CloudFormation from automatically replacing your function when needed.

Configure retention policies for Alexa skills

Add DeletionPolicy: Retain and UpdateReplacePolicy: Retain policies to your Lambda function resource in your SAM template. Place these definitions at the same level as Type and Properties.

YAML
Raw JSON

Copied to clipboard.

Resources:
  AlexaSkillFunction:
    Type: AWS::Serverless::Function
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      Handler: index.handler
      Runtime: nodejs18.x

Copied to clipboard.

{
  "Resources": {
    "AlexaSkillFunction": {
      "Type": "AWS::Serverless::Function",
      "DeletionPolicy": "Retain",
      "UpdateReplacePolicy": "Retain",
      "Properties": {
        "Handler": "index.handler",
        "Runtime": "nodejs20.x"
      }
    }
  }
}

For details, see DeletionPolicy attribute and UpdateReplacePolicy attribute in the AWS CloudFormation documentation.

Create a Lambda function from scratch

You can create a new Lambda function from scratch with the Lambda console. Use this method if you aren't using the ASK SDK for Node v2 or ASK SDK for Python.

To create a new Lambda function

If you do not already have an account on AWS, go to AWS and create an account.
Log in to the AWS Management Console and navigate to AWS Lambda.
From the Region drop-down list in the upper-right corner of the console, select one of the allowed AWS regions.

See Select the optimal region for your AWS Lambda function to determine which one you should choose.
If you have no Lambda functions yet, click Get Started Now. Otherwise, click Create a Lambda Function.
Enter a Name for the function.
Select the Role for the function. This defines the AWS resources the function can access.
- To use an existing role, select the role under Existing role.
- To create a new role, see Define a new role for the function, below
Select the language you want to use for the Runtime. If you are using one of the Alexa Skills Kit SDKs, select Node, Python, or Java. For the list of languages supported by Lambda, see AWS Lambda Runtimes in the AWS Lambda documentation.
Click Create function.

You can now do any of the following:

View and edit the code for the Lambda function
Connect the Lambda function to your skill
Configure the Alexa Skills Kit triggers
Test a Lambda Function in the console

Define a new role for the function

The role specifies the AWS resources your function can access. To create a new role while configuring your function:

For Role (under Lambda function handler and role), select Create new role from template(s).
Enter the Role Name.
From the Policy templates list, select Simple Microservice permissions.

View and edit the code for the Lambda function

To view and edit the code, click the name of the function under Designer, then scroll down to the Function code section.

From here, you can do any of the following, depending on the runtime you selected:

For Alexa-Hosted skills, write your code directly in the Code tab in the Alexa developer console. For more details, see Create and Manage Alexa-Hosted Skills.
Write your code directly in the code editor in the Lambda console.
Write your code offline and copy and paste it into the Lambda console editor.
Write your code offline and upload it to the Lambda function in a zip or jar file. For details, see Deploy Node.js Lambda functions with .zip file archives, Working with .zip file archives for Python Lambda functions, or Deploy Java Lambda functions with .zip or JAR file archives.
Use Alexa Skills (ASK) Toolkit for Visual Studio Code (VS Code).
Use the Eclipse IDE and the AWS Toolkit for Eclipse For details, see Using AWS Lambda with the Toolkit for Eclipse.

For more about the tools you can use to author your function, see Authoring Code for Your Lambda Function .

Connect the Lambda function to your skill

To connect the function with your skill, you need to update the Endpoint field for your skill to the AWS Lambda Amazon Resource Name (ARN) for your function.

Tip: Lambda creates a new version of your function each time that you publish the function. You can use the ARN for a specific version, or you can create an alias for a Lambda function version. Use an alias ARN to invoke a different version as you make enhancements to your Lambda function. For more details, see Lambda function aliases.

To connect the Lambda function to your skill

Copy the ARN shown in the upper-right corner of your Lambda function.
Open or create your skill in the developer console.
Navigate to Custom > Endpoint.
For the Service Endpoint Type, select AWS Lambda ARN, then paste the ARN for your Lambda function in the Default Region box.

Configure the trigger for a Lambda function

You must configure at least one trigger for your function to grant Alexa the necessary invocation permissions for your function.

When you add the Alexa Skills Kit as a trigger, Amazon recommends that you also enable skill ID verification for the function and provide the skill ID (also called the application ID) for your skill. This means your function can be invoked only if the skill ID in the Alexa Skills Kit request matches the skill ID configured in the trigger.

When using skill ID verification, you don't include code to verify that the request is intended for your service. Requests from unverified skills don't invoke your function.

Multiple Skills Calling the Same Function

You can configure multiple triggers if you want to invoke the same Lambda function from multiple skills. In this case, each trigger must be configured with a unique skill ID.

Note: You may have older Lambda functions that have skill ID verification setup as part of the function's code as described in Verify that the Request is Intended for Your Service. They don't include skill ID verification in the trigger. These functions will continue to work and verify the skill ID when these functions are run. However, Amazon recommends that you update the triggers to include the skill ID to perform the check at invocation. To do so, Remove the old trigger, then add a new trigger with the ID.

Add an Alexa Skills Kit trigger

Before you add the trigger, copy the skill ID from the developer console:

Open or create your skill in the developer console.
Find the skill in the list and click Copy Skill ID below the skill name. Copy the ID from the popup.

Once you have your skill ID, add the trigger to the function:

Log in to the AWS Management Console and navigate to AWS Lambda.
Click your function in the list to open the configuration details.
Make sure you are on the Configuration page.
In the Designer section, under Add triggers, click Alexa Skills Kit to select the trigger.
Under Configure triggers, select Enable for Skill ID verification.
Enter your skill ID in the Skill ID edit box.
Click Add.
Click Save to save the change.

It is highly recommended that you limit invocation permissions to just Alexa and enable skill ID verification to protect your function from malicious callers.

Tip: If you need to invoke the same function from multiple skills, follow the steps above to add the Alexa Skills Kit trigger multiple times.

Remove an Alexa Skills Kit trigger

You can remove a trigger from your function in the Lambda console. This also removes the skill ID verification for any skill ID included in the trigger.

Log in to the AWS Management Console and navigate to AWS Lambda.
Click your function in the list to open the configuration details.
Make sure you're on the Configuration page. Existing triggers for the function are displayed in the Designer section at the top of the page.
Click the Alexa Skills Kit box in the Designer section to display the Alexa Skills Kit triggers previously added to your skill. They are shown in an Alexa Skills Kit section at the bottom of the page.
Click the Delete button next to each trigger to delete.
Click Save to save the change.

Change an existing trigger

You can't edit an existing trigger for a Lambda function. To change a trigger (for instance, to add or change the skill ID), remove the old trigger, then add a new trigger.

Configure triggers with the AWS CLI or Lambda API

AWS Lambda provides both an API and command line interface (CLI) for managing Lambda functions. You can use these tools to add or remove the Alexa Skills Kit trigger as well. These let you add a resource-based policy granting the Alexa Skills Kit permission to invoke the function.

For the API, use AddPermission.
For the AWS CLI, use the add-permission command.

For the Alexa Skills Kit trigger, you must set the following:

action must be lambda:InvokeFunction.
principal must be alexa-appkit.amazon.com.
event-source-token is the ID for your skill.

For example, this CLI command adds the trigger to the Lambda function hello_world:

aws lambda add-permission
    --function-name hello_world
    --statement-id 1
    --action lambda:InvokeFunction
    --principal alexa-appkit.amazon.com
    --event-source-token amzn1.ask.skill.xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

For details about the API and CLI, see AddPermission and add-permission .

Triggers added with the API or CLI are displayed in the Lambda console just like all other triggers.

Disable Skill ID verification

You can configure your function to not use skill ID verification if absolutely necessary. For instance, you may want to turn off the verification in an environment in which you have a large number of skills invoking the same function for testing purposes. It is still recommended that you re-enable verification before publishing your skill.

To disable skill ID verification in the Lambda console:

Remove any existing triggers that are configured with skill ID verification
Add a new Alexa Skills Kit trigger as described above and select Disable for Skill ID verification.

To disable skill ID verification with the Lambda API or CLI:

Remove any existing triggers that are configured with skill ID verification. For details about the Lambda API and CLI, see RemovePermission (API) and remove-permission (CLI).
Add a new resource-based policy granting the Alexa Skills Kit permission to invoke the function, but do not set the EventSourceToken.

For example, this CLI command adds the trigger to the Lambda function hello_world, but without skill ID verification:

aws lambda add-permission
    --function-name hello_world
    --statement-id 1
    --action lambda:InvokeFunction
    --principal alexa-appkit.amazon.com

See AWS documentation for details about using the Lambda API or CLI.

If you later want to re-enable skill ID verification (recommended before publishing the skill), delete any triggers that don't include the EventSourceToken, then add a new trigger and include the skill ID.

Note: Note that a trigger without the EventSourceToken overrides triggers that do include this condition. Be sure to delete any triggers without the skill ID when you re-enable skill ID verification.

Test a Lambda function in the console

You can manually test a Lambda function in the Lambda console by sending sample JSON events formatted in the same way as requests sent by Alexa. Sample events are provided for testing within the console. You can use these events as a starting point and modify them to represent requests that the Alexa service would send to your own function. Note that you can also send events to a Lambda function using the AWS CLI.

The Lambda console does not check the conditions on the function's triggers, so your test event does not need to have a matching skill ID when you use skill ID verification.

For details about the JSON interface, see Request and Response JSON Reference.

To test your function, you need to create a new test event:

In the Function list, click the function name to open the details for the function.
In the upper right corner of the screen, click the Select a test event drop-down list and click Configure test events.
Select Create new test event and then select one of the sample Alexa requests from the Event template list:
- Alexa Start Session
- Alexa Intent (multiple samples available)
- Alexa End Session
Enter an Event name.
Click Create.
On the main function configuration page, make sure your event is selected and click the Test button.

You can configure multiple events to test sending different requests to your function.

Tip: If you get an error when you test the function, make sure your test event is a valid Alexa request. Make sure you are creating your event from one of the Alexa templates, not a different Lambda template such as "Hello World".

After the function runs, the Execution result section shows the response returned by the function, in JSON format. You should see a response appropriate for the request pasted into the Sample event box. For example, for a LaunchRequest, a function built from the alexa-skills-kit-nodejs-premium-facts-skill template returns a response similar to this:

{
  "version": "1.0",
  "response": {
    "outputSpeech": {
      "type": "SSML",
      "ssml": "<speak>Welcome to Premium Facts Sample. To hear a random fact you can say 'Tell me a fact', or to hear about the premium categories for purchase, say 'What can I buy'.  For help, say , 'Help me'... So, What can I help you with?</speak>"
    },
    "reprompt": {
      "outputSpeech": {
        "type": "SSML",
        "ssml": "<speak>I didn't catch that. What can I help you with?</speak>"
      }
    },
    "shouldEndSession": false
  },
  "userAgent": "ask-node/2.3.0 Node/v8.10.0",
  "sessionAttributes": {}
}

The Log output section shows any log messages generated by the code. The sample writes a log message for each type of request, so you should see something like the following:

2015-05-18T23:53:22.357Z    0f885f98-fdb9-11e4-80af-1b9f8363b496    onIntent requestId=amzn1.echo-api.request.6919844a-733e-4e89-893a-fdcb77e2ef0d, sessionId=amzn1.echo-api.session.abeee1a7-aee0-41e6-8192-e6faaed9f5ef

Tip: You can also test your skill in the developer console. When troubleshooting and debugging, it can be useful to copy the JSON for a request from the Skill I/O: JSON Input field in the developer console into a new test event in the Lambda console. Then you can make changes to the request and see any log messages immediately.

Sample code

The following sample code demonstrates a basic Hello World skill and other features of the ASK SDK: