The SimpleEventSource API enables smart home developers to leverage Alexa Routines to increase customer engagement

Staff Writer May 10, 2023
Share:
Smart Home
Blog_Header_Post_Img

Today, we’re announcing the new SimpleEventSource API to enable smart home device makers to publish custom events generated by their devices. Events represent an action or state transition of smart home devices — for example the press of a button, a swipe on a device or the transition between the open and closed states of a garage door.

The SimpleEventSource API offers developers compelling new ways to increase customer engagement with their devices. Developers can now define custom events generated by their devices to initiate Alexa Routines. Routines are short cuts for Alexa that help customers to automate their homes, like turning off the lights and adjusting the thermostat at bedtime. They save time by grouping together a series of actions so customers don’t have to ask for each one individually. By creating new ways that customers can initiate Routines, developers can dramatically improve engagement for their devices. Routines users have four times the engagement and 40% higher retention compared to non-Routine users. Today, more than 30% of smart home interactions are now initiated by Alexa—without customers saying anything—that’s thanks to predictive and proactive features like Routines and Hunches.

With the SimpleEventSource API, Philips Hue can now enable customers to control any smart device in their home such as turning on the lights and opening the shades in their room by simply pressing a button on their Hue remote. Customers can use the Philips Hue dimmer switch, Tap dial switch, and smart button to trigger Routines in the U.S., so Alexa can read them the news and turn on all the lights in their homes at the push of a button. In addition, Hue customers can now choose to initiate other Alexa actions: for example, they can simply press a button on their remotes to have Alexa start their morning routine and turn on the lights, read the news, and start the coffee maker. 

“The SimpleEventSource API has opened new opportunities for Philips Hue customers to interact and control their smart homes with remotes,” said George Yianni, CTO Philips Hue at Signify. "The API gives us the flexibility to onboard all our smart buttons and switch offerings and gives customers immediate access to new actions via Alexa. We are excited to see all the new ways customers use them.” 

Prior to today’s announcement, developers could publish events for a limited number of device categories such as doorbells and motion sensors. The SimpleEventSource API expands developer capabilities by allowing them to define custom events across all device categories and customer use cases; for example, garage doors can send events when the door is opening to turn on nearby lights in the home, or a coffee machine can send a notification when it has been left on for too long.

Developers should refer to the controller documentation for their device category to determine if there are event sources specific to their device before using the SimpleEventSource API.

Getting started with the SimpleEventSource API: Custom events

The SimpleEventSource API allows developers to model any kind of event that customers may find useful for creating automations not already covered by existing event sources. Developers can add the SimpleEventSource capability to their device by defining the instances that send events and the supported event types for a device in the Discovery payload. 

Using a remote device as an example, developers can define an instance for each button on the device (e.g. “power button”, “brighten button”) and an event for the types of actions a customer can take (e.g. pressing the button once or holding the button down). Below is a snippet of the discovery payload for a device that has two buttons: “power” and “brighten”. Each button supports a single push and double push.

Copied to clipboard
{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            ...
        "payload": {
            "endpoints": [{
                "endpointId": "EndpointId-01",
                "manufacturerName": "BrandName",
                "friendlyName": "Dimmer 01",
                "description": "Dimmer Remote",
                "displayCategories": ["REMOTE"],
                ...
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.SimpleEventSource",
                        "instance": "Unique identifier, preferably a version 4 UUID",
                        "version": "1.0",
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "asset",
                                "value": {
                                    "assetId": "Alexa.Button.PowerButton"
                                }
                            }]
                        },
                        "configuration": {
                            "supportedEvents": [{
                                "id": "Unique identifier, preferably a version 4 UUID",
                                "friendlyNames": [{
                                    "@type": "asset",
                                    "value": {
                                        "assetId": "Alexa.Button.SinglePush"
                                    }
                                }]
                            },
                            {
                                "id": "Unique identifier, preferably a version 4 UUID",
                                "friendlyNames": [{
                                    "@type": "asset",
                                    "value": {
                                        "assetId": "Alexa.Button.DoublePush"
                                    }
                                }]
                            }]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.SimpleEventSource",
                        "instance": "Unique identifier, preferably a version 4 UUID",
                        "version": "1.0",
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "asset",
                                "value": {
                                    "assetId": "Alexa.Button.BrightenButton"
                                }
                            }]
                        },
                        "configuration": {
                            "supportedEvents": [{
                                "id": "Unique identifier, preferably a version 4 UUID",
                                "friendlyNames": [{
                                    "@type": "asset",
                                    "value": {
                                        "assetId": "Alexa.Button.SinglePush"
                                    }
                                }]
                            },
                            {
                                "id": "Unique identifier, preferably a version 4 UUID",
                                "friendlyNames": [{
                                    "@type": "asset",
                                    "value": {
                                        "assetId": "Alexa.Button.DoublePush"
                                    }...

Utilizing the SimpleEventSource API to initiate Alexa Routines

Customers configure routines with instances and events developers defined with any combination of Alexa actions. When the event happens, the skill or device will send that event to Alexa. Make sure to only send the event once as Alexa will trigger the routine every time an event is sent.

Using the previous remote device example, if the customer pressed the “power” button, the event payload would contain the following:

Copied to clipboard
{
    "event": {
        "header": {
            "namespace": "Alexa.SimpleEventSource",
            "name": "Event",
            "payloadVersion": "1.0",
            "messageId": "abc-123-def-456",
            "instance": "Unique identifier, preferably a version 4 UUID",
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "token"
            },
            "endpointId": "EndpointId-01",
            "cookie": {} 
        },
        "payload": {
            "id": "Button.SinglePush",
            "timestamp": 2022-05-16T19:39:44Z
        },
        "context": {}
    }
}

Developers can review the SimpleEventSource API documentation here and join leading brands in integrating their devices and custom events with Alexa to make their smart home device a part of customers’ daily routines. 

Recommended reading

Alexa adds iOS Setup, Thread support, and surpasses 100 million Matter-enabled Echos
Three questions with Yiwen Xu, Alexa’s go-to-market lead for Matter
Melissa Cha is helping shape the future of the smart home and smart health at Amazon

Subscribe