Receive Events for Alexa Smart Properties

Note: Sign in to the developer console to build or publish your skill.

Note: This functionality is only available for Alexa Smart Properties subscriptions in US.

When you integrate your organization with Alexa Smart Properties, you can subscribe to events from Alexa. These events enable you to take actions such as raising alarms and retrying operations. For example, you might want to create an alarm for skill time-out events so that you can make sure that the web services that power your skill are running correctly.

Events are published to Amazon Simple Notification Service (SNS). To set up event publishing, see Steps to set up events.

Events

There are currently five available events. For details about the event schemas, see Event Schemas.

Enterprise subscription activation
Automation execution completion
Skill interaction failure
Role management
Setup completion

Enterprise subscription activation

This event is generated after you create a unit in a property. When you create a unit by using the Alexa Smart Properties console or the REST API, a success message just means that the unit was created. However, operations (such as creating child units, enabling skills, or associating devices) are blocked on that unit until Alexa Smart Properties initializes the subscription.

This event triggers when the subscription on the unit is initialized. When you receive this event, you know you can perform your next operation (such as creating a child unit) without having to wait for the period of time that Alexa Smart Properties recommends.

This event is delivered within 10 seconds of the subscription activation.

Automation execution completion

This event is generated when the actions you specify in an automation template successfully or unsuccessfully complete. Actions can fail to run when the automation has the incorrect endpoint ID or unit ID, or when there is an internal server error.

Alexa Smart Properties delivers an automation failure event if the automation action runs (for example, the automation attempts to reset the volume to five) but for some reason the action doesn't complete (for example, the volume remains at 10). This situation can happen when there are network connectivity issues. For example, when you use the Automation REST API to update settings, there's a chance that the setting hasn't been updated on the device.

This event is delivered within 10 seconds of the automation execution completion.

Skill interaction failure

This event is generated when a user tries to interact with a skill but the skill either times out (and therefore Alexa doesn't respond), or the skill returns an invalid response. Invalid responses can happen for the following reasons:

The skill endpoint doesn't exist.
The skill returned an exception.
The skill endpoint contained invalid SSML.

This event gives you insight into errors that logging within your skill can't capture. Skill Interaction Failure events are delivered within 10 minutes of the error occurring.

Role management

This event is generated after assignment or revocation of a role using the Role API has completed. When you set the propagate flag to true when assigning or revoking a role, the API returns a success message. However, the roles of the sub-units aren't necessarily assigned to the principal at that time. This means that the principal can't act on the sub units. When you assign a role to a principal without setting the propagate flag to be true, the role is assigned or revoked when the API returns a success or failure message.

This event triggers a role has been assigned or revoked for a principal both if the roles are assigned or revoke using propagation or not using propagation. When you receive this event, you know the principal can perform the next operation without having to wait for the period of time that Alexa Smart Properties recommends.

Setup completion

This event is generated when a device has completed the retail setup experience and is ready to be fleet managed by associating it to a unit. Specifically, this event is generated when a device has connected to the internet, has been registered to the Amazon account, and any automatic software updates have been downloaded and installed (for multimodal devices).

You can use this event to automatically associate a device to a unit by listening to the event and then executing the associatedUnits API in Endpoints API. You can pass the endpointID provided in the event to the associateUnits API call and move the device to its target unit without having to visually confirm that the device is ready to associate. This event is triggered for all Echo devices (both Show devices and devices without screens).

NOTE: To use this event you must provide the user_id for the account used to setup devices. Obtain the user_id by running GET: https://api.amazon.com/user/profile with the scope profile. You can use a tool such as postman to run this request..

Prerequisites

To set up events for Alexa Smart Properties, you must have the following prerequisites:

Amazon developer account – If you don't already have a developer account, sign up at developer.amazon.com.
AWS account – You configure Alexa to send events to an endpoint, and the available endpoint is currently Amazon SNS. To set up Amazon SNS, you must have an AWS account.

Steps to set up events

The following steps show you how to set up events for Alexa Smart Properties:

Step 1: Create an Amazon SNS topic.
Step 2: Create a subscription configuration.
Step 3: Create a subscription.

Step 1: Create an Amazon SNS topic

Before you configure Alexa to send events, you must set up an Amazon SNS topic for Alexa to send the events to. After you create the SNS topic, you add an AWS Identity and Access Management (IAM) access policy to the SNS topic so that Alexa has permission to publish events to the SNS topic.

To create and add permissions to an Amazon SNS topic

Log in to your AWS account and navigate to the Amazon SNS console.
On the left, click Topics. On the upper right, click Create topic.
Enter a topic name, and then click Create topic.
From the Details section, make note of the Amazon Resource Name (ARN) of the topic.
Click the Access policy tab.
At the upper right, click Edit.

Expand Access policy, and then incorporate the following policy into the existing policy.

Note: Replace the Resource value with the topic ARN that you copied from the Details section of the SNS topic's page a few steps ago.

 {
     "Sid": "grant-alexa-event-sns-publish",
     "Effect": "Allow",
     "Principal": {
     "AWS": [
         "arn:aws:iam::006860194444:role/AlexaEventConsumerSnsIamRole"
     ]
     },
     "Action": "sns:Publish",
     "Resource": "the-arn-of-the-sns-topic"
 }

At the bottom, click Save changes.
Important: If this permission is removed at any time, Alexa doesn't guarantee delivery of events to the SNS topic. To prevent any accidental changes to this permission, we recommend that you monitor IAM policy changes on your AWS account while you have an active subscription for events.
Specify how you want to read events from the SNS topic by following one of these instructions:

Step 2: Create a subscription configuration

In this step, you configure Alexa to send events to the SNS topic that you created. This information is represented by a subscription configuration. You create a subscription configuration by using the Event Messenger API as described in the following procedure.

To create a subscription configuration

Use a REST client to call the Create a subscription configuration operation.
As described in Create a subscription configuration, put the following information in the request:
- In the header of the request, include an access token as the bearer token of the Authentication header.
- In the body of the request, include a deliveryChannels array that contains the ARN of the SNS topic that you created in step 1.

If the subscription configuration details are valid, Alexa creates a subscription configuration and the operation returns HTTP 201 Created. As shown in the following example, the Location header of the HTTP response lists the id, which is a unique identifier for the subscription configuration resource.

Location: amzn1.alexa.aem.subscription.configuration.123

The information is also included in the id parameter in the body of the response.

Step 3: Create a subscription

A subscription specifies which events trigger a notification. You create a subscription by using the Event Messenger API as described in the following procedure.

To set up a subscription

Use a REST client to call the Create a subscription operation.
As described in Create a subscription, put the following information in the request:
- In the header of the request, include an access token as the bearer token of the Authentication header.
- In the body of the request, include the following information:
  - the event type. You can find available event types in Event Schemas.
  - the ID of the subscription configuration that you created in the previous step.
  - A list of entities that you to associate with the event.

If the subscription details are valid, Alexa creates an event subscription and the operation returns HTTP 201 Created. As shown in the following example, the Location header of the HTTP response lists the id, which is a unique identifier for the subscription resource.

Location: amzn1.alexa.aem.subscription.123