A
AcceptGrant TheAlexa.Authorization.AcceptGrant directive Alexa sends to your add-on after account linking completes, to start the event gateway authorization flow. Your add-on must handle this directive when you turn on the Send Alexa Events permission. For more details, see Alexa.Authorization and Request Access to the Alexa Event Gateway.
access token
An OAuth 2.0 bearer token that identifies and authenticates the customer to access their data. Alexa includes the access token in the scope of directives so your add-on can associate the request with the correct customer account. You also include a separate access token when you send asynchronous events to the Alexa event gateway so your add-on can access customer data in their Alexa account. For more details, see Validate and Use Access Tokens in Smart Home and Video Code.
account linking
The process of connecting the Alexa user’s Amazon identity with their identity in your system. All smart home add-ons must implement account linking using OAuth 2.0 and the authorization code grant type. During account linking, your authorization server grants Alexa an access token that your add-on later uses to identify the customer. For more details, see Account Linking for Smart Home and Other Domains.
authorization code
A short-lived code your authorization server returns to Alexa after the user signs in. During account linking, Alexa exchanges the authorization code with your token server for an access and refresh token pair. In the Alexa event gateway flow, Alexa also sends an Amazon authorization code in the Alexa.Authorization.AcceptGrant directive. For more details, see Account Linking Concepts and Send Events to the Alexa Event Gateway.
authorization code grant
The OAuth 2.0 grant type required for smart home account linking. Alexa obtains an authorization code from your authorization server, exchanges it for an access and refresh token pair, and then includes the access token in requests to your add-on. For more details, see Account Linking Concepts.
authorization server
The server that signs in the user to your system, authenticates their identity, issues an authorization code, and exchanges that code for an access token. Because it handles token exchanges, it is sometimes called a token server. You can build your own OAuth 2.0 server or use a provider, such as Login with Amazon (LWA). For more details, see Account Linking Concepts.
AddOrUpdateReport
An event you send to proactively notify Alexa after a customer adds a new endpoint or renames or updates an existing one. Proactive updates let a device appear in the Alexa app without the customer running discovery again. For more details, see Alexa.Discovery.
Alexa Automated Testing Service (ATS)
A tool in the Alexa developer console that you use to test device control for your Alexa-connected smart home devices. ATS supports both smart home add-ons and Matter implementations. You create test plans with natural language. ATS sends voice commands to your device through Alexa and validates the responses and state change reports. For more details, see Use the Alexa Automated Testing Service.
Alexa app
The mobile app that customers use to set up devices, change settings, group devices, and view the state of their Alexa-connected smart home devices. Information you provide during discovery, such as the friendly name and display category, determines how a device appears in the app.
Alexa Built-in (ABI)
A device that has the Alexa Voice Service (AVS) client integrated directly, so customers can speak to Alexa through the device. You can control an ABI device and its endpoints through the built-in client, and you can report relationships that associate smart home endpoints with the ABI device.
Alexa Connect Kit (ACK)
A managed connectivity solution that adds Alexa and Matter support to your device. With ACK, Amazon manages the cloud infrastructure, security, certification, and over-the-air (OTA) updates, so you can focus development on your device application. For more details, see What is the Alexa Connect Kit?.
Alexa developer console
The web-based tool you use to create, configure, test, and publish your smart home add-on. In the console, you configure account linking, set permissions, view operational metrics such as accuracy rate, and run the Alexa Automated Testing Service (ATS). For more details, see the Alexa developer console.
Alexa event gateway
The endpoint to which you send asynchronous events, such as Alexa.ChangeReport and proactive discovery updates. To send events, you request permission from the customer and obtain an access token, which you include in the scope of the event message. For more details, see Send Events to the Alexa Event Gateway.
Alexa interface (Alexa namespace)
The single foundational interface that every add-on must support. It defines the messages common to all add-ons, including discovery, state reporting, change reporting, and error reporting. You explicitly declare support for the Alexa interface for every endpoint in your discovery response. The Alexa interface is distinct from capability interfaces, such as Alexa.PowerController, that model device features. For more details, see Alexa Interface.
Alexa.Response
The event (Alexa.Response) you send to Alexa after you successfully handle a directive. In the response, you include the current state of all retrievable properties in the context object so Alexa has a complete snapshot of the endpoint. You can send the response synchronously from your Lambda function or asynchronously to the Alexa event gateway. For most interfaces, Alexa waits eight seconds for your response before it times out. For more details, see Alexa.Response Interface.
Alexa Voice Service (AVS)
A cloud-based service that lets you add Alexa voice capabilities directly to your product. When you integrate AVS, your device becomes an Alexa Built-in (ABI) device that customers can speak to directly. For more details, see Alexa Voice Service.
Alexa+
Amazon’s next-generation voice assistant, powered by generative AI. Alexa+ is built on large language models (LLMs) available on Amazon Bedrock.
AWS Lambda
The Amazon Web Services (AWS) serverless compute service where you host your smart home add-on code. Your Lambda function receives directives from Alexa and sends synchronous responses, such as an Alexa.StateReport, typically within eight seconds.
B
Bluetooth Low-Energy (BLE) mesh A low-power wireless networking protocol you can use to connect your smart home device directly to Alexa without a smart home add-on or a separate hub. Most Amazon Echo devices can discover and control BLE-mesh devices, such as light bulbs and plugs. For more details, see Understand Smart Home Bluetooth Mesh Support.C
capability A unit of functionality that an endpoint exposes, declared in the discovery response by including the corresponding capability interface. For example, a dimmable light declares theAlexa.PowerController and Alexa.BrightnessController capability interfaces. A combination of capabilities describes what a device can do. For the full set of smart home capability interfaces, see List of Alexa Interfaces and Supported Languages.
certification
The Amazon review process a product goes through to confirm it meets Alexa quality requirements before launch. Smart home products can earn the Works with Alexa (WWA) badge after passing certification. For more details, see Works with Alexa Overview.
ChangeReport
An event (Alexa.ChangeReport) you send proactively to Alexa when a reportable property changes for any reason, such as a manual interaction with the device. Alexa expects a change report within three seconds of a state change. For more details, see Alexa.ChangeReport.
cluster
In Matter, a group of related attributes and commands that defines a piece of device functionality. When you certify a Matter product, you implement the required clusters for your device category and map them to the corresponding Alexa capability interfaces. For the mapping, see Alexa Supported Matter Device Categories and Clusters.
commissioning
The process of adding and securely onboarding a Matter device to a network and fabric. For Matter over Thread, a Thread border router commissions the device before it joins the network. For more details, see Connect Your Device to Alexa with Matter.
Connectivity Standards Alliance (CSA)
The industry organization that develops and maintains the Matter standard. The CSA issues the Matter Vendor ID and Matter Product ID that you encode in your device firmware. For more details, see Connect Your Device to Alexa with Matter.
context object
The part of an Alexa smart home message that contains the current values of all retrievable properties for an endpoint. You include the context object in an Alexa.StateReport, Alexa.ChangeReport, and Alexa.Response to give Alexa a complete snapshot of the endpoint state. For more details, see Understand State and Change Reporting.
customIdentifier
An ID that you provide for an endpoint during discovery, in addition to the required endpointId. Alexa uses the customIdentifier to understand when endpoints controlled over Matter and add-ons are the same device, improving the customer experience in the Alexa app. For more details, see Alexa.Discovery.
D
Dash Replenishment A service that lets a device automatically reorder physical goods from Amazon, such as a printer reordering ink. To be part of the Dash Replenishment program, you add device management and certify the device with the Dash Replenishment Service. For more details, see About Dash Replenishment. DeleteReport An event you send to proactively notify Alexa when a customer removes an endpoint from their account. Sending aDeleteReport lets Alexa remove the device from the Alexa app without the customer running discovery again. For more details, see Alexa.Discovery.
device cloud
Your back-end cloud service that controls your cloud-connected devices and stores customer accounts and device information. Your smart home add-on, hosted on AWS Lambda, translates Alexa directives into calls to your device cloud and relays device state back to Alexa. For more details, see Smart Home Add-on Concepts.
device cloud account
The account a customer uses to access your device cloud. During account linking, the customer connects their device cloud account with their Amazon account so Alexa can control their devices. For more details, see Account Linking for Smart Home and Other Domains.
directive
A message Alexa sends to your add-on to request an action or information, such as a TurnOn directive from Alexa.PowerController or an Alexa.ReportState directive. Your add-on handles the directive and sends back a response event. For more details, see Steps to Build Smart Home Add-ons.
discovery
The process by which Alexa learns about a customer’s connected devices. After a customer enables your add-on and links their account, Alexa sends an Alexa.Discovery.Discover directive, and your add-on returns a response describing each endpoint, its capabilities, and any required configuration. For more details, see About Alexa Discovery.
display categories
A property you set for each endpoint during discovery that determines the icon and placement of the device in the Alexa app, such as LIGHT, TV, or OVEN. Alexa also uses the display category to help select the correct voice-interaction behavior. For the list of categories, see Alexa.Discovery.
E
endpoint A representation of a connected device associated with a customer’s account. An endpoint can be a physical device, a virtual device, a group or cluster of devices such as a scene, or a software component. Each endpoint has a uniqueendpointId and a set of capabilities. For more details, see About Alexa Discovery.
EndpointHealth
The Alexa.EndpointHealth interface, which reports the health of a device, such as connectivity. Amazon recommends implementing it for all devices, and it is required for sensor devices and for Works with Alexa certification. For more details, see Alexa.EndpointHealth.
endpointId
A unique ID that you assign to each endpoint in your discovery response. Alexa uses the endpointId to route directives to the correct device and to correlate state and change reports. The endpointId must be unique within your add-on and must not exceed 256 characters. For more details, see Alexa.Discovery.
event
A JSON message your smart home add-on sends to Alexa, either as an asynchronous response to a directive or a proactive event, such as an Alexa.ChangeReport. You send events to the Alexa event gateway. For more details, see Send Events to the Alexa Event Gateway.
F
fabric In Matter, a logical grouping of devices that share a common root of trust and can communicate securely with each other. When a Matter device is commissioned, it joins a fabric. Alexa-enabled devices, such as Echo and eero, can act as controllers on the fabric. For more details, see Connect Your Device to Alexa with Matter. friendly name The name a customer uses to refer to a device when speaking to Alexa, such as “Living Room Light.” You set an initial friendly name during discovery, and the customer can later change it in the Alexa app. For more details, see Friendly Name Resources and Assets. Frustration-Free Setup (FFS) An Amazon program that simplifies device setup. With Frustration-Free Setup, a customer powers on a compatible device and it automatically connects to their Wi-Fi network and registers with their Amazon account, without manual configuration. FFS is a required feature that you must integrate into your ACK-based devices. For more details, see Understanding Frustration-Free Setup.G
generic controller A general-purpose capability interface, such asAlexa.ModeController, Alexa.RangeController, or Alexa.ToggleController, that you use to model device components that do not have a dedicated specific controller. Generic controllers support multiple instances per device and semantics. For more details, see Generic Controller Interfaces.
I
instance A named occurrence of a generic controller on an endpoint. Because you can implement several instances of a generic controller on one device, you give each an instance name in the discovery response, such asFan.Speed and Fan.Light for a ceiling fan with a light. For more details, see Generic Controller Interfaces.
L
Login with Amazon (LWA) An OAuth 2.0 authorization service you can use to authenticate customers and link their device account with their Amazon account. You can use LWA or your own OAuth 2.0 provider for account linking. For more details, see Account Linking for Smart Home and Other Domains.M
Matter An IP-based wireless connectivity standard designed for interoperability between devices from different manufacturers. With Matter, smart home devices can connect directly to Alexa without a separate hub or add-on, which reduces latency and improves reliability. Alexa supports Matter over Wi-Fi and over Thread. For more details, see Connect Your Device to Alexa with Matter. Matter bridge A device that exposes non-Matter devices to a Matter fabric as bridged devices. If your add-on connects Matter-enabled devices to Alexa, either native Matter devices or devices behind a Matter bridge, you report Matter attributes from your add-on. For more details, see Connect Your Device to Alexa with Matter. Matter Product ID A 16-bit ID that uniquely identifies your product. The Matter Product ID (PID) is issued by the Connectivity Standards Alliance (CSA) and encoded in your device firmware. For more details, see Connect Your Device to Alexa with Matter. Matter Vendor ID A 16-bit ID that uniquely identifies the manufacturer, vendor, or ecosystem. The Matter Vendor ID (VID) is issued by the Connectivity Standards Alliance (CSA) and encoded in your device firmware. For more details, see Connect Your Device to Alexa with Matter.O
OAuth 2.0 The authentication framework Alexa uses for account linking. OAuth 2.0 lets a user grant Alexa permission to access their data on your server without sharing their password. Smart home account linking requires OAuth 2.0 and the authorization code grant type. For more details, see Account Linking Concepts. over-the-air (OTA) update A wireless firmware update delivered to a device after you deploy it in the field. With Alexa Connect Kit (ACK), Amazon manages OTA updates for you, so your device receives security patches and feature improvements automatically. For Matter devices, Alexa supports OTA updates over the local network. For more details, see What is the Alexa Connect Kit?.P
proactively reported A discovery parameter (proactivelyReported) you set per interface to indicate that you send an Alexa.ChangeReport whenever a reportable property of that interface changes. Setting it to true lets Alexa display current device state in the Alexa app and on Alexa-enabled devices with a screen. For more details, see Understand State and Change Reporting.
property
A named, reportable value of a capability interface, such as powerState for Alexa.PowerController or brightness for Alexa.BrightnessController. You declare supported properties during discovery and report their values in state and change reports. For the interfaces and their properties, see List of Alexa Interfaces and Supported Languages.
R
Real-Time Communication (RTC) The capability that enables real-time streaming of audio and video between Alexa and your smart home device, used for device types such as cameras and doorbells. For more details, see About the Real-Time Communication Interface. refresh token A credential used to request a new access token after the current one expires. For account linking, the Alexa service refreshes the token automatically. For the event gateway flow, your add-on uses the refresh token to request new tokens from Login with Amazon (LWA), typically about every 60 minutes. For more details, see Request Access to the Alexa Event Gateway. relationships The discovery object you use to describe how linked endpoints relate to each other, such as a soundbar controlled by an Alexa Built-in device, or endpoints reported over Matter and your add-on. Reporting relationships lets related devices display together under a parent device in the Alexa app. For more details, see About Alexa Discovery. ReportState The directive (Alexa.ReportState) Alexa sends to request the current state of an endpoint, for example when a customer opens the Alexa app. You respond with an Alexa.StateReport containing the current values of all retrievable properties. For more details, see Alexa.ReportState and Alexa.StateReport Interfaces.
retrievable
A discovery parameter (retrievable) you set per interface to indicate that Alexa can query the current state of the add-on’s reportable properties. When set to true, Alexa can send an Alexa.ReportState directive and expect an Alexa.StateReport in return. For more details, see Understand State and Change Reporting.
S
scene A group or cluster of devices modeled as a single endpoint, so a customer can control several devices together. You model scenes with theAlexa.SceneController interface. For more details, see Alexa.SceneController.
semantics
An optional feature of generic controllers that maps extra phrases, such as “open,” “close,” “raise,” and “lower,” to your controller’s directives, and that can enable Alexa hunches and announcements. Each semantic phrase must be unique across all controller instances for an endpoint. For more details, see Generic Controller Interfaces.
smart home add-on
Code, typically hosted on AWS Lambda, that connects your cloud-connected devices to Alexa over Wi-Fi. The add-on handles Alexa directives, reports device state, and communicates with your device cloud. Building an add-on requires your own cloud infrastructure and an OAuth 2.0 server. For more details, see Connect Your Device Cloud with Smart Home Add-ons.
Smart Home AI Toolkit
An AI-assisted development tool that you use to build custom smart home capability interfaces. You chat with the Alexa+ smart home agent to describe your device and the agent generates the interface definition, test utterances, and a device control UI for the Alexa app. For more details, see Add Custom Capabilities with the Smart Home AI Toolkit.
Smart Home API
The set of Alexa interfaces you implement to give Alexa control of smart home devices such as lights, thermostats, and locks. The API translates customer utterances into directives that Alexa routes to your add-on. For the full set of interfaces, see List of Alexa Interfaces and Supported Languages.
specific controller
A purpose-built capability interface for a particular device feature, such as Alexa.PowerController, Alexa.BrightnessController, or Alexa.ThermostatController. Specific controllers produce the most natural utterances, but allow only one instance per endpoint. For the full set of interfaces, see List of Alexa Interfaces and Supported Languages.
state and change reporting
The mechanism that keeps Alexa informed of device state. You report state when Alexa requests it (Alexa.StateReport), proactively when state changes (Alexa.ChangeReport), and in response to a directive (Alexa.Response). Accurate reporting is essential to the customer experience and required for WWA certification. For more details, see Understand State and Change Reporting.
StateReport
The response (Alexa.StateReport) you send to an Alexa.ReportState directive. It contains a snapshot of the current values of all retrievable properties for an endpoint, reported in the context object. For more details, see Alexa.ReportState and Alexa.StateReport Interfaces.
T
Thread An IPv6-based, low-power wireless mesh-networking technology designed for security, reliability, and scalability. Thread-enabled Amazon Echo and eero devices can act as Thread border routers. For more details, see Understand Smart Home Thread Support. Thread border router A device, such as a Thread-enabled Echo or eero, that connects a Thread mesh network to other IP networks and commissions Thread-based smart home devices before they join the network. For more details, see Understand Smart Home Thread Support.U
utterance What a customer says to Alexa to control a device, such as “Alexa, turn on the living room light.” Each capability interface provides a pre-built voice-interaction model that defines the supported utterances, some interfaces use Alexa+ LLM inference to handle a wider variety of user utterances. For more details, see About Alexa Discovery.V
Video APIs The APIs you use to build Alexa add-ons for video devices and streaming services, enabling far-field voice control through interfaces such asAlexa.ChannelController, Alexa.PlaybackController, Alexa.RemoteVideoPlayer, and Alexa.Launcher. For more details, see Video APIs.
voice-interaction model
The pre-built language model Alexa automatically enables for each capability you support, based on your device description. The model defines the utterances customers use to control the device, so you don’t build a custom interaction model for smart home. For more details, see About Alexa Discovery.
