Alexa.Commissionable Interface
Implement the Alexa.Commissionable
interface in your Alexa skill to help Alexa connect with your endpoints locally on your customer’s home network over a local protocol, such as Matter. After Alexa connects to your endpoints locally, you have an alternate route available for executing control directives. This route makes control of your endpoints faster and more resilient if there are network outages or when your skill isn't available. For details about integrating your Matter devices with Amazon, see Matter on developer.amazon.com.
For the list of locales that the Alexa.Commissionable
interface supports, see List of Alexa Interfaces and Supported Languages.
Utterances
The Alexa.Commissionable
interface isn't customer-facing, therefore it doesn't support any voice user interactions with Alexa directly.
Workflow
Alexa.Commissionable
seamlessly integrates into existing customer and developer workflows. As usual, the customer first registers their device with your app and then enables your smart home skill by account linking your app with their Amazon account. For details about account linking with Alexa, see Set up App-to-App Account Linking for Your Skill. The commissioning of your device with Alexa starts when one of the following activities happens:
- When a customer asks Alexa to discover their device, Alexa sends a
Discover
directive to your skill and your skill reports theDiscover.Response
event with theAlexa.Commissionable
capability for the first time for that endpoint. For additional information, see Discovery. - When your skill proactively reports your device with the
Alexa.Commissionable
capability by using theAddOrUpdateReport
event. For additional information, see AddOrUpdateReport.
After receiving the Discover.Response
event or the AddOrUpdateReport
event with the Alexa.Commissionable
capability, Alexa sends the ReportCommissioningInformation
directive to request commissioning information for the device. After your skill sends a CommissioningInformationReport
, Alexa initiates a workflow to trigger a local commissioning.
This diagram illustrates the Discovery workflow when the customer hasn't enabled your skill. Click the image to enlarge.

This diagram illustrates the AddOrUpdateReport workflow when the customer has already enabled your skill. Click the image to enlarge.

Matter protocol specific requirements
For Matter devices, apply the following settings in your Alexa.Discovery Discover.Response
or AddOrUpdateReport
event report:
- In the
Endpoint
object, make sure that thefriendlyName
reported from your skill is also available over the local Matter connection through theNodeLabel
field from the Basic Information Cluster of the device. If the customer changes the friendly name on your app, you should update theNodeLabel
field to reflect the change. - In the
AdditionalAttributes
object, populate thecustomIdentifier
field with the stableUniqueID
field from the Basic Information Cluster of the device. You use this field to deduplicate devices reported through your skill and locally from the Alexa device. - In the
Connections
property, report the type as aMATTER
connection. Amazon recommends that you report thematterDiscriminator
,macAddress
,matterVendorId
,matterProductId
, andmacNetworkInterface
of your Matter device if the values are available.
macAddress
to Alexa proactively via the Alexa Event Gateway. For more information, see Send Events to the Event Gateway. Discovery
You describe your device's endpoints that support Alexa.Commissionable
by using the standard discovery mechanism described in the Alexa.Discovery
Interface and Alexa Discovery Objects / Connections property. When you report the Alexa.Commissionable
capability in your discovery response report, Alexa knows that a device is available in your customer's account and is ready to be paired locally with an Echo device.
Apply Matter specific settings as described in Matter protocol specific requirements.
Discovery response example
The following example shows a Discover.Response
message for an endpoint that supports Alexa.Commissionable
and Alexa.EndpointHealth
interfaces.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "a unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "unique ID of the endpoint",
"manufacturerName": "the manufacturer name of the endpoint",
"description": "a description that is shown in the Alexa app",
"friendlyName": "New Matter device",
"displayCategories": ["LIGHT"],
"additionalAttributes": {
"manufacturer": "the manufacturer name of the endpoint",
"model": "the model of the device",
"serialNumber": "the serial number of the device",
"firmwareVersion": "the firmware version of the device",
"softwareVersion": "the software version of the device",
"customIdentifier": "your custom identifier for the device"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.Commissionable",
"version": "1.0"
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
],
"connections": [{
"type": "MATTER",
"macAddress": "00:11:22:AA:BB:33:44:55",
"macNetworkInterface": "THREAD",
"matterVendorId": "MatterVendorId",
"matterProductId": "MatterProductId",
"matterDiscriminator": "longDiscriminator"
} ],
"relationships": {}
}]
}
}
}
AddOrUpdateReport
To commission an existing endpoint or a new Matter endpoint, for example, to Matter-enable an existing endpoint with a firmware update, you can proactively send an Alexa.Discovery.AddOrUpdateReport
event. For details, see the AddOrUpdateReport
event.
Apply Matter specific settings as described in Matter protocol specific requirements.
AddOrUpdateReport event example
The following example shows an AddOrUpdateReport
message for a new endpoint to indicate that an Echo device can commission this device.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "a unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "unique ID of the new endpoint",
"manufacturerName": "the manufacturer name of the endpoint",
"description": "a description that is shown in the Alexa app",
"friendlyName": "New Matter device",
"displayCategories": ["LIGHT"],
"additionalAttributes": {
"manufacturer": "the manufacturer name of the endpoint",
"model": "the model of the device",
"serialNumber": "the serial number of the device",
"firmwareVersion": "the firmware version of the device",
"softwareVersion": "the software version of the device",
"customIdentifier": "your custom identifier for the device"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.Commissionable",
"version": "1.0"
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
],
"connections": [{
"type": "MATTER",
"macAddress": "00:11:22:AA:BB:33:44:55",
"macNetworkInterface": "THREAD",
"matterVendorId": "MatterVendorId",
"matterProductId": "MatterProductId",
"matterDiscriminator": "longDiscriminator"
} ],
"relationships": {}
}]
}
}
}
Directives and events
ReportCommissioningInformation directive
When the Discover.Response
or AddOrUpdateReport
event includes the Alexa.Commissionable
capability, Alexa sends the ReportCommissioningInformation
directive to your skill. Using this directive, Alexa asks your device cloud to take necessary actions to enable local commissioning. In the case of the Matter protocol, the follow actions occur. After receiving this directive, your device cloud puts your device in the commissioning mode for a given period and returns commissioning credentials. Also, your device cloud returns the commissioning window expiration timestamp that indicates the duration that the device should stay in the commissioning mode.
ReportCommissioningInformation
directive example
The following example shows a ReportCommissioningInformation
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.Commissionable",
"name": "ReportCommissioningInformation",
"messageId": "message id",
"correlationToken": "an opaque correlation token",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2 bearer token"
},
"endpointId": "endpoint id",
"cookie": {}
},
"payload": {}
}
}
ReportCommissioningInformation
directive response event
After your skill successfully handles the ReportCommissioningInformation
directive and puts the device in commissioning mode, respond with a CommissioningInformationReport
event.
CommissioningInformationReport event payload
The following table shows the payload details for the CommissioningInformationReport
response event.
Property | Description | Type | Required |
---|---|---|---|
|
An array of protocol objects, which is a list of local protocols over which Alexa can pair with a device. The protocol objects |
Array of objects |
Yes |
|
A string enumeration value that indicates the protocol for commissioning with this device on a local network. The valid value is |
String |
Yes |
|
Object containing protocol specific commissioning data, including |
Object |
Yes |
|
A Matter device generates this code when the current administrator instructs the device to go into the open commissioning window. |
String |
Yes |
|
An optional timestamp your skill provides to indicate the commissioning window, after which Alexa can no longer create a local connection. This timestamp helps Alexa limit the retries until a specific time and also troubleshoot when Alexa is unable to create a local connection because the commissioning window has expired. The timestamp represents a specific date and time in Coordinated Universal Time. It's a string that uses the RFC 3339 profile of the ISO 8601 format, |
String |
No |
Example response event
The following example shows a successful response event that you send to the ReportCommissioningInformation
directive.
{
"event": {
"header": {
"namespace": "Alexa.Commissionable",
"name": "CommissioningInformationReport",
"messageId": "a unique identifier, preferably a version 4 UUID",
"correlationToken": "an opaque correlation token",
"payloadVersion": "1.0"
},
"endpoint": {
"endpointId": "endpoint id"
},
"payload": {
"commissioningInformation": [{
"localProtocol": "MATTER",
"protocolData": {
"manualPairingCode": "ManualPairingCode",
"commissioningWindowExpirationTimestamp": "2021-02-03T16:20:50Z"
}
}
]
}
}
}
ReportCommissioningInformation directive error handling
If your skill can't handle a ReportCommissioningInformation
directive successfully, respond with a ReportCommissioningInformation.ErrorResponse
event.
In addition to the ReportCommissioningInformation
error types, you can use standard Alexa error types, such as ENDPOINT_BUSY
, ENDPOINT_UNREACHABLE
, and BRIDGE_UNREACHABLE
. For details, see ErrorResponse Events / Error type values.