Alexa Interface

The Alexa interface is the top-level interface for Alexa skills and 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 Interface Message Guide.

For the full list of Alexa interfaces, see List of Alexa Interfaces.

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 also 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": "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": "<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

The Alexa interface defines the following directive and responses:

  • AcceptGrant directive – Alexa gives you credentials that identify and authenticate the customer to Alexa.
  • Discover directive – The customer asks Alexa to connect their device to your smart home skill.
  • 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 to let Alexa know.
  • 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.