Alexa.SimpleEventSource Interface 1.0

Implement the Alexa.SimpleEventSource interface to model stateless events, such as a button press on a remote or an occupant entering a room. Users can connect the events to Alexa routines. For example, after the user presses a button on their remote switch or smart button, Alexa triggers a routine to dim their smart bulbs to 25 percent and close the blinds. The Alexa.SimpleEventSource interface is a generic controller interface.

For the list of languages that the Alexa.SimpleEventSource interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the Alexa message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.SimpleEventSource interface doesn't have any user utterances. The customer interacts with your device, and the associated event triggers an Alexa routine.

Reportable properties

The Alexa.SimpleEventSource interface doesn't define any reportable properties.

An endpoint can support multiple instances of the Alexa.SimpleEventSource. You must always include the instance ID in your events and responses. You identify your instance ID in your discovery response.

Discovery

You describe endpoints that support Alexa.SimpleEventSource by using the standard discovery mechanism described in Alexa.Discovery.

Set the display category to the one most appropriate for your device, such as REMOTE. For the full list of display categories, see display categories.

Capabilities array

In addition to the usual discovery response fields, for each Alexa.SimpleEventSource entry in the capabilities array, include the following fields.

Property Description Type Required

instance

Unique identifier for the instance, preferably a version 4 UUID.
The identifier must be unique across instances and endpoints.

String

Yes

capabilityResources

Friendly names that users can use to refer to the button or gestures supported by your device. Alexa displays these names in the Alexa app and customers can use the friendly name to identify entities on your device that can trigger events.
You can use assets from the global Alexa catalog or define your own friendly names and localized text.
For REMOTE devices, use the instance assets friendly names.

CapabilityResources object

Yes

configuration.supportedEvents

A list of events that this device supports. You must define at least one event.

Array of objects

Yes

configuration.supportedEvents[*].id

Unique identifier used to refer to this event.

String

Yes

configuration.supportedEvents[*].friendlyNames

Friendly names for the event. Alexa displays these names in the Alexa app and customers can use the friendly name to trigger an Alexa routine.
The first friendly name in the array must be unique per instance of the capability. You can use assets from the global Alexa catalog or define your own friendly names as text.
For REMOTE devices, use the event assets friendly names.

Array of Label objects

Yes

Assets for the REMOTE display category

Alexa defines instance and event friendly name assets for the REMOTE display category in the global Alexa catalog. If you use another display category, define friendly names that best describe the instance and events for your device.

Instance friendly name assets

For REMOTE devices, you can use the following localized, friendly name assets to identify entities on your device that can trigger events, such as the buttons on a remote or an occupant entering a room. Or, you can define your own friendly names.

Asset identifier Supported friendly names

Alexa.Button.OffButton

Off button

Alexa.Button.OnButton

On button

Alexa.Button.BrightenButton

Brighten button

Alexa.Button.DimButton

Dim button

Alexa.Button.MainButton

Main button

Alexa.Button.TopButton

Top button

Alexa.Button.BottomButton

Bottom button

Alexa.Button.CenterButton

Center button

Alexa.Button.MiddleButton

Middle button

Alexa.Button.UpButton

Up button

Alexa.Button.DownButton

Down button

Alexa.Button.LeftButton

Left button

Alexa.Button.RightButton

Right button

Alexa.Button.FirstButton

First button

Alexa.Button.SecondButton

Second button

Alexa.Button.ThirdButton

Third button

Alexa.Button.FourthButton

Fourth button

Alexa.Button.FifthButton

Fifth button

Alexa.Button.SixthButton

Sixth button

Alexa.Button.SeventhButton

Seventh button

Alexa.Button.EighthButton

Eighth button

Event friendly name assets

For REMOTE devices, you can use the following localized, friendly name assets to identify actions that trigger an event. For example, a button might support both a single push or a double push. Or, you can define your own friendly names.

Asset identifier Supported friendly names

Alexa.Button.DoublePress

Double press

Alexa.Button.DoublePush

Double push

Alexa.Button.LongPress

Long press

Alexa.Button.LongPush

Long push

Alexa.Button.SinglePress

Single press

Alexa.Button.SinglePush

Single push

Alexa.Gesture.DoubleClick

Double click

Alexa.Gestures.DoubleTap

Double tap

Alexa.Gesture.SingleClick

Single click

Alexa.Gesture.SwipeDown

Swipe down

Alexa.Gesture.SwipeLeft

Swipe left

Alexa.Gesture.SwipeRight

Swipe right

Alexa.Gesture.SwipeUp

Swipe up

Alexa.Gesture.Tap

Tap

Discovery response example

The following example shows a Discover.Response message for a remote switch that supports the Alexa.SimpleEventSource interface. The switch has four buttons with one event per button.

Directives and events

The Alexa.SimpleEventSource interface doesn't define any directives, but does define an event.

SimpleEvent event

Send a SimpleEvent message to the Alexa event gateway to notify Alexa proactively that the user triggered the specified event on the specified event source. For details, see Send Events to the Event Gateway.

SimpleEvent example

The following example shows a SimpleEvent to notify Alexa that an event, identified as Button.SinglePush fired on the specified instance.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.SimpleEventSource",
            "name": "Event",
            "instance": "Unique identifier, preferably a version 4 UUID",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "payloadVersion": "1.0"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2 bearer token"
            },
            "endpointId": "Endpoint id",
            "cookie": {}
        },
        "payload": {
            "id": "Button.SinglePush.1",
            "timestamp": "2021-12-12T16:20:50:52Z"
        }
    }
}

SimpleEvent payload

The following table shows the payload details for the SimpleEvent event.

Property Description Type Required

id

Identifies the event that fired. You defined the event id in your discovery response.

String

No

timestamp

Time the endpoint detected the event.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

SimpleEvent response

If Alexa handles the event successfully, your skill receives HTTP status code 202 Success from the Alexa event gateway. On error, Alexa sends the appropriate HTTP status code.

HTTP status codes

The following table shows the HTTP status code values that your skill might receive from the Alexa event gateway. If you receive an error, the payload object contains a code and description field. Use these fields for logging only.

Status Payload code Description

202 Accepted

Request is authorized and the message is a syntactically valid event. The event was accepted for further logical validation and processing.

400 Bad Request

INVALID_REQUEST_EXCEPTION

Message is invalid due to missing fields, incorrect values, or malformed JSON. Check your messages against the documentation to verify that your message contains all the required fields.

401 Unauthorized

INVALID_ACCESS_TOKEN_EXCEPTION

Message didn't include the authorization token or the token is invalid, expired, or malformed. Refresh your token and retry the request. If a user disables your skill, that also invalidates the access token. Here, the user revoked authorization, and you can stop sending change reports for them.

403 Forbidden

SKILL_NEVER_ENABLED_EXCEPTION

You're not allowed access to the event gateway. Make sure that you're sending the events to the correct regional endpoint. For example, send events in North America to the North American endpoint.

403 Forbidden

INSUFFICIENT_PERMISSION_EXCEPTION

Token doesn't have the required permissions. Make sure that the skill has permission to send Alexa events. For details, see Request Access to the Alexa Event Gateway.

404 Not Found

ACCOUNT_NOT_FOUND_EXCEPTION

Account record associated with this directed identifier doesn't exist or has expired. This error can occur if the event was sent too late or with an invalid directed identifier. Verify that the directed identifier and authorization code are correct.

404 Not Found

SKILL_NOT_FOUND_EXCEPTION

Skill ID associated with this token wasn't found. This error occurs when user's access token was generated when the skill was in different stage, such as certification. Try disabling and re-enabling the skill for this user.

413 Payload Too Large

REQUEST_ENTITY_TOO_LARGE_EXCEPTION

Size of the event payload is too large. The maximum number of endpoints allowed in a request is 300. Send your message with smaller payloads.

429 Too Many Requests

THROTTLING_EXCEPTION

Number of requests is too high. Resend the message up to three times, with at least a one-second interval between each send attempt.

500 Internal Server Error

INTERNAL_SERVICE_EXCEPTION

Error occurred with Alexa, and the message wasn't processed. Resend the message up to three times, with at least a one-second interval between each send attempt. If problems persist, contact Amazon Support.

503 Service Unavailable

SERVICE_UNAVAILABLE_EXCEPTION

Alexa couldn't accept the message. Resend the message up to three times, with at least a one-second interval between each attempt. If the problem persists, contact Amazon Support.

Example 401 Unauthorized response body

The following example shows an error response.

HTTP/1.1 400 Bad Request
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
  },
  "payload": {
      "code": "INVALID_ACCESS_TOKEN_EXCEPTION",
      "description": "The access token is invalid, expired, or malformed."
  }
}

Change reporting

You send a ChangeReport event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.