• Documentation
  • Pricing
© 2026 Serverless, Inc. All rights reserved.

Framework

  • Overview
  • Documentation
  • Plugins360
  • Pricing

Learn

  • Blog
  • GuidesUpdated
  • Examples240
  • Courses

Resources

  • Support
  • Security
  • Trust Center
  • Status

Community

  • Slack
  • GitHub47k
  • Forum
  • Meetups

Company

  • About
  • Careers
  • Contact
  • Partners

Legal

  • Terms of Service
  • Privacy Policy
  • Trademark
  • DMCA
Serverless Framework Logo

Serverless Framework

Intro
SetupUpgrading To V4ConceptsTutorialAWS CredentialsLicense Keys
DeployingPackagingBuildingTestingDev ModeServicesFunctions
OverviewHTTP (API Gateway v2)REST (API Gateway v1)ActiveMQApplication Load BalancerAlexa SkillAlexa Smart HomeCloudWatch EventCloudWatch LogCloudFrontCognito User PoolEventBridge EventIoTIoT Fleet ProvisioningKafkaKinesis & DynamoDBMSKRabbitMQS3ScheduleSNSSQSWebsocket
LayersManaged InstancesWeb Apps (Lambda Web Functions)Sandboxes (Lambda MicroVMs)MCP ServersAlertsVersion PruningDomainsIAM Function PermissionsParameters
OverviewSelf-reference serverless.ymlServerless CoreEnvironment VariablesCLI OptionsExternal YAML/JSON FilesJavascript propertiesGitDoppler
OverviewS3 ObjectsSSM Parameter Store & Secrets ManagerCloudFormation Stack Outputs
OverviewVaultTerraform State Output
ResourcesComposing ServicesDeployment BucketStateAgent SkillsPython support
OverviewRuntimeGatewayMemoryBrowserCode InterpreterDev Mode
API Gateway Proxy
OverviewGeneral ConfigurationAuthenticationAPI KeysData SourcesResolversPipeline FunctionsSubstitutionsCachingDelta SyncCustom DomainWAFCLI Commands
Deploying SAM/CFN TemplatesWorkflow Tips
OverviewCreating PluginsCLI OutputCustom CommandsCustom VariablesExtending the Configuration schemaExtending and overriding configuration
OverviewDashboardAxiom
Overviewagent docsagent inspectagent setupagent skills installagent skills list / readdeploydeploy functiondeploy listdevdiffinfoinvokeinvoke localloginlogin awslogin aws ssologsmetricspackageplugin installplugin uninstallprintprunereconcileremoverollbackrollback functionusage
OverviewConcepts
OverviewMetricsTracesTroubleshoot
OverviewNode.jsPython
OutputsProviders
OverviewBranch DeploymentsPreview DeploymentsCustom ScriptsTestingPrivate PackagesNotificationsMono ReposDeploy in your own CI/CDBest PracticesTroubleshootingFAQ
OverviewSetupToolsAWS Integration
Serverless.yml Reference
Examples and TutorialsConfiguration Validation
  1. Usage
  2. Events
  3. Alexa Smart Home

Alexa Smart Home Events

The alexaSmartHome event lets an Alexa smart home skill (called a smart home add-on in the Alexa+ developer docs) invoke your Lambda function, the same as adding an Alexa Smart Home trigger with the skill ID in the Lambda console. The Framework doesn't create the skill: you create it in the Alexa developer console, give its skill ID to the event, and set the skill's endpoint to the deployed function. For a custom voice skill, use Alexa Skill events instead.

The following serverless.yml deploys a function that only the smart home skill amzn1.ask.skill.12345678-1234-1234-1234-123456789012 can invoke:

# serverless.yml
service: my-smart-home

provider:
  name: aws
  runtime: nodejs24.x
  region: us-east-1

functions:
  smartHome:
    handler: handler.handler
    events:
      - alexaSmartHome: amzn1.ask.skill.12345678-1234-1234-1234-123456789012

Replace the skill ID with your own; the developer console shows it after you create the skill. Smart home skills call Lambda functions in a Region that depends on the skill's language (see Lambda Region for a smart home skill).

Connect a deployed function to a smart home skill

The skill sends directives to the function only after its endpoint is set to the function's ARN:

  1. Deploy the service with serverless deploy.
  2. Run serverless info and note the deployed function name, by default <service>-<stage>-<function> (my-smart-home-dev-smartHome for the preceding example).
  3. In the Alexa developer console, open the skill and enter the function ARN as its service endpoint, for example arn:aws:lambda:us-east-1:123456789012:function:my-smart-home-dev-smartHome.
  4. Configure account linking, which every smart home skill needs, and test the skill in the Alexa app, as Steps to Build Smart Home Add-ons describes.

When the function uses provisionedConcurrency, SnapStart or durable functions, the Framework attaches the alexaSmartHome permission to the function's alias (provisioned or the name set in provisionedConcurrency.alias, snapstart, or durable), so enter the alias ARN instead, for example arn:aws:lambda:us-east-1:123456789012:function:my-smart-home-dev-smartHome:provisioned.

alexaSmartHome event settings

The alexaSmartHome event takes either the skill ID as a string or an object with these keys:

KeyTypeDefaultDescription
appIdStringRequiredThe skill ID, such as amzn1.ask.skill.12345678-1234-1234-1234-123456789012. Letters, digits, ., _ and -, up to 256 characters.
enabledBooleantrueWhether the skill can invoke the function.

The string form is the same as the object form with only appId. To let several skills invoke one function, add one alexaSmartHome event per skill ID; each creates its own permission.

Disable an Alexa Smart Home trigger

To stop a smart home skill from invoking the function without removing the event, set the alexaSmartHome event's enabled to false:

functions:
  smartHome:
    handler: handler.handler
    events:
      - alexaSmartHome:
          appId: amzn1.ask.skill.12345678-1234-1234-1234-123456789012
          enabled: false

With enabled: false, the Framework keeps the permission resource but sets its action to lambda:DisableInvokeFunction, which doesn't allow invocation. Set enabled back to true, or remove the key, and deploy again to restore it.

AWS resources and permissions for alexaSmartHome events

For each alexaSmartHome event, the Framework adds one AWS::Lambda::Permission resource to the stack, with the logical ID <FunctionName>LambdaPermissionAlexaSmartHome<N> (for example SmartHomeLambdaPermissionAlexaSmartHome1). The permission has:

  • Principal alexa-connectedhome.amazon.com.
  • Action lambda:InvokeFunction (lambda:DisableInvokeFunction when enabled: false).
  • EventSourceToken set to the skill ID, so only that skill can invoke the function.

The function's execution role needs no extra permissions for this event. The Framework creates no Alexa resources; the skill, its account linking and its endpoints stay in the Alexa developer console.

Lambda Region for a smart home skill

Alexa sends smart home directives to the Lambda function in the AWS Region that serves the skill's language: US East (N. Virginia) us-east-1 for North America, EU (Ireland) eu-west-1 for Europe and India, and US West (Oregon) us-west-2 for the Far East and Australia. Develop Smart Home Add-ons in Multiple Languages maps each language to its Region. For a skill in several of these Regions, deploy the service once per Region with serverless deploy --region <region> and enter each function ARN as that Region's endpoint.

Smart home directive format

Alexa invokes the function with a directive and expects an event in response, both described in the Alexa Interface Message and Property Reference. The directive's header.namespace and header.name name the interface and operation, such as Alexa.Discovery and Discover; the payload.scope.token (or endpoint.scope.token for device directives) carries the user's OAuth 2.0 access token from account linking. The following trimmed Discover directive shows the shape:

{
  "directive": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
    },
    "payload": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-account-linking"
      }
    }
  }
}

The following handler.mjs answers Discover with an empty device list; a real skill returns the user's devices in endpoints and handles the other directives its devices support:

// handler.mjs
import { randomUUID } from 'node:crypto'

export const handler = async (event) => {
  const { namespace, name } = event.directive.header

  if (namespace === 'Alexa.Discovery' && name === 'Discover') {
    return {
      event: {
        header: {
          namespace: 'Alexa.Discovery',
          name: 'Discover.Response',
          payloadVersion: '3',
          messageId: randomUUID(),
        },
        payload: { endpoints: [] },
      },
    }
  }

  throw new Error(`Unsupported directive ${namespace}.${name}`)
}

Alexa.Discovery Interface lists the endpoint fields a Discover.Response returns.

Related

  • Alexa Skill events: invoke a function from an Alexa custom skill.
  • Steps to Build Smart Home Add-ons: the Alexa guide for building a smart home skill.
  • serverless.yml reference: Alexa: every alexaSmartHome key in one place.
  • Serverless examples: services to start from.
Edit this page
Prev Alexa SkillNextCloudWatch Event

Contents

  • Alexa Smart Home Events
  • Connect a deployed function to a smart home skill
  • alexaSmartHome event settings
  • Disable an Alexa Smart Home trigger
  • AWS resources and permissions for alexaSmartHome events
  • Lambda Region for a smart home skill
  • Smart home directive format
  • Related

Related

GuidesPluginsExamplesSlack CommunitySupport