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.

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. To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

Capabilities array

An endpoint can support multiple instances of Alexa.SimpleEventSource, so you must always include the instance ID in your events and responses. Define an instance for each interface and schema that the same endpoint supports in the capabilities object. 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 ID for the instance, preferably a version 4 UUID. The ID 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.

Example

{
    "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": "Remote switch with four buttons",
                "friendlyName": "Alexa.Button",
                "displayCategories": ["REMOTE"],
                "additionalAttributes": {
                    "manufacturer": "Manufacturer of the endpoint",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.SimpleEventSource",
                        "instance": "Unique identifier, preferably a version 4 UUID",
                        "version": "1.0",
                        "properties": {},
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "asset",
                                "value": {
                                    "assetId": "Alexa.Button.OnButton"
                                }
                            }]
                        },
                        "configuration": {
                            "supportedEvents": [{
                                "id": "Button.SinglePush.1",
                                "friendlyNames": [{
                                    "@type": "asset",
                                    "value": {
                                        "assetId": "Alexa.Button.SinglePush"
                                    }
                                }]
                            }]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.SimpleEventSource",
                        "instance": "Unique identifier, preferably a version 4 UUID",
                        "version": "1.0",
                        "properties": {},
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "asset",
                                "value": {
                                    "assetId": "Alexa.Button.OffButton"
                                }
                            }]
                        },
                        "configuration": {
                            "supportedEvents": [{
                                "id": "Button.SinglePush.2",
                                "friendlyNames": [{
                                    "@type": "asset",
                                    "value": {
                                        "assetId": "Alexa.Button.SinglePush"
                                    }
                                }]
                            }]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.SimpleEventSource",
                        "instance": "Unique identifier, preferably a version 4 UUID",
                        "version": "1.0",
                        "properties": {},
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "asset",
                                "value": {
                                    "assetId": "Alexa.Button.BrightenButton"
                                }
                            }]
                        },
                        "configuration": {
                            "supportedEvents": [{
                                "id": "Button.SinglePush.3",
                                "friendlyNames": [{
                                    "@type": "asset",
                                    "value": {
                                        "assetId": "Alexa.Button.SinglePush"
                                    }
                                }]
                            }]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.SimpleEventSource",
                        "instance": "Unique identifier, preferably a version 4 UUID",
                        "version": "1.0",
                        "properties": {},
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "asset",
                                "value": {
                                    "assetId": "Alexa.Button.DimButton"
                                }
                            }]
                        },
                        "configuration": {
                            "supportedEvents": [{
                                "id": "Button.SinglePush.4",
                                "friendlyNames": [{
                                    "@type": "asset",
                                    "value": {
                                        "assetId": "Alexa.Button.SinglePush"
                                    }
                                }]
                            }]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

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.

{
    "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` or `YYYY-MM-DDThh:mm:ss.SSSZ`	String	Yes

SimpleEvent response

If Alexa handles the event successfully, your add-on 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 add-on might receive from the Alexa event gateway. If you receive an error, the response body contains the error code and description. Use these fields for logging only.

Status	Payload code	Description
`202 Accepted`	—	Request is authorized and the message is a syntactically valid event. The gateway accepted the event for further logical validation and processing.
`400 Bad Request`	`INVALID_REQUEST_EXCEPTION`	Message is not valid 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 expired, malformed, or not valid. Refresh your token and retry the request. If a user disables your add-on, that also invalidates the access token.
`403 Forbidden`	`SKILL_DISABLED_EXCEPTION`	The customer disabled your add-on. Stop sending events for the customer and delete any stored tokens in your system.
`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. Otherwise, the customer never enabled your add-on.
`403 Forbidden`	`INSUFFICIENT_PERMISSION_EXCEPTION`	Token doesn’t have the required permissions. Make sure that the add-on 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 directed identifier that’s not valid. 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 add-on was in different stage, such as certification. Try disabling and re-enabling the add-on 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 error response body

The following example shows an error response.

HTTP/1.1 401 Unauthorized
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "Unique version 4 UUID"
  },
  "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.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa.SimpleEventSource Interface 1.0

Utterances

Reportable properties

Discovery

Capabilities array

Assets for the REMOTE display category

Instance friendly name assets

Event friendly name assets

Discovery response example

Directives and events

SimpleEvent event

SimpleEvent example

SimpleEvent payload

SimpleEvent response

HTTP status codes

Example error response body

Change reporting

​Utterances

​Reportable properties

​Discovery

​Capabilities array

​Assets for the REMOTE display category

​Instance friendly name assets

​Event friendly name assets

​Discovery response example

​Directives and events

​SimpleEvent event

​SimpleEvent example

​SimpleEvent payload

​SimpleEvent response

​HTTP status codes

Example error response body

​Change reporting

​Related topics

Utterances

Reportable properties

Discovery

Capabilities array

Assets for the REMOTE display category

Instance friendly name assets

Event friendly name assets

Discovery response example

Directives and events

SimpleEvent event

SimpleEvent example

SimpleEvent payload

SimpleEvent response

HTTP status codes

Change reporting

Related topics