Alexa Interface 3

The Alexa interface is the top-level interface for Alexa skills that defines the Alexa foundational messages that all skills use. These APIs include general Alexa directives, response events, discovery, state reporting, change reporting, and error reporting. For details, see Alexa Message Reference.

For the full list of Alexa capability interfaces, see List of Alexa Interfaces. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Support the Alexa interface in all skills

You must explicitly identify your support for the Alexa interface in the Discover.Response and AddOrUpdateReport event messages. For more details about the discovery interface, see the Alexa.Discovery interface.

The following example shows a discovery response for an endpoint that supports the Alexa.PowerController. You explicitly identify your support for the Alexa interface. For more discovery examples, see the documentation for each interface.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints":[
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "Manufacturer of the endpoint",
          "description": "Description to be shown in the Alexa app",
          "friendlyName": "Device name, displayed in the Alexa app",
          "displayCategories": ["LIGHT"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives and responses

Along with the directives and events defined for each capability interface, the Alexa interface defines the following foundational directives and events:

  • AcceptGrant directive – Alexa gives you credentials that identify and authenticate the customer to Alexa.
  • Discover directive – Alexa requests the capabilities of the customer endpoints.
  • ReportState directive – Alexa wants to announce or display the state of a device connected to your smart home or video skill.
  • AddOrUpdateReport event – After the customer adds or updates a device connected to your skill, you send the event to let Alexa know about the new or updated device.
  • DeleteReport event – After the customer deletes a device connected to your smart home skill, you send the event to let Alexa know that the device no longer exists.
  • StateReport response – You send state reports to respond to report state directives to let Alexa know the state of the devices that your skill controls.
  • ChangeReport event – You send change report events to proactively report when the state of a device changes.
  • Response event – You send responses to interface-specific directives.
  • DeferredResponse event – You send a deferred response event after certain directives to notify Alexa that your actual response comes later.
  • ErrorResponse – If you can't handle interface-specific directives successfully, you send error responses to indicate the failure reason.
Was this page helpful?

Last updated: Nov 22, 2023