Event Messenger REST API Reference

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

Note: This API is only available to registered Alexa Smart Properties partners. For more details, see Get Started with Alexa Smart Properties APIs.

Use the Event Messenger REST API to 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. Alexa publishes events to the Amazon Simple Notification Service (SNS).

First, you create an SNS topic, and then you create a subscription configuration to define a delivery channel for Alexa events. Last, you create a subscription that specifies the type of event you want to subscribe to and which delivery channel to use. For details about how to use the Event Messenger API, see Receive Events for Alexa Smart Properties.

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

API endpoint

In the request header, set Host to the following, depending on the region of your organization: https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.

Operations

The Event Messenger API includes the following operations.

Operation	HTTP Method and URI
Create subscription configuration	`POST /v1/eventMessenger/subscriptionConfigurations`
Delete subscription configuration	`DELETE /v1/eventMessenger/subscriptionConfigurations/{id}`
Get subscription configuration by ID	`GET /v1/eventMessenger/subscriptionConfigurations/{id}`
List subscription configurations	`GET /v1/eventMessenger/subscriptionConfigurations?owner={owner}&maxResults={maxResults}&nextToken={nextToken}`
Create subscription	`POST /v1/eventMessenger/subscriptions`
Delete subscription	`DELETE /v1/eventMessenger/subscriptions/{id}`
Get subscription by ID	`GET /v1/eventMessenger/subscriptions/{id}`
List subscriptions	`GET /v1/eventMessenger/subscriptions?owner={owner}&entities.unit.id={unitId}&entities.unit.type={entityType}&entities.unit.parent.id={parentId}&entities.unit.parent.type={parentType}&eventType.namespace={nameSpace}&eventType.names={name}&maxResults={maxResults}&nextToken={nextToken}`

Create subscription configuration

Create a subscription configuration, which defines a delivery channel that multiple subscriptions can use.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To create a subscription configuration, you make a POST request to the /v1/eventMessenger/subscriptionConfigurations resource.

Request path and header example

Copied to clipboard.

POST /v1/eventMessenger/subscriptionConfigurations
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header and path parameters

Parameter	Located in	Description	Type	Required
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
  "deliveryChannels": [{
    "type": "SNS",
    "id": "arn:aws:sns:us-east-1:0123456789:AlexaEvents"
  }]
}

Request body properties

Property	Description	Type	Required
`deliveryChannels`	List of delivery mechanism configuration objects.	Array of objects	Yes
`deliveryChannels[].type`	Type of delivery channel. Valid values: `SNS`.	String	Yes
`deliveryChannels[].id`	Identifies the delivery channel. Set to the Amazon Resource Name (ARN) of the SNS topic to which to publish events.	String	Yes

Response

A successful response returns HTTP 201 Created, along with the subscription configuration ID. The response header also includes a link to the subscription configuration ID in the Location parameter. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The following example shows the body of a successful response.

{
  "id": "amzn1.alexa.aem.subscription.configuration.123"
}

Response body properties

Property	Description	Type
`id`	Unique ID of the subscription configuration. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.configuration.{id}`.	String

HTTP status codes

Status	Description
`201 Created`	Subscription configuration created successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete subscription configuration

Deletes the specified subscription configuration.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To delete a subscription confirmation, you make a DELETE request to the /v1/eventMessenger/subscriptionConfigurations/{id} resource.

Request path and header example

Copied to clipboard.

DELETE /v1/eventMessenger/subscriptionConfigurations/{id}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header and path parameters

Parameter	Located in	Description	Type	Required
`id`	Path	Unique ID of the subscription configuration to delete. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.configuration.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Subscription configuration deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. Retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get subscription configuration by ID

Get a subscription configuration by configuration ID.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To get a subscription configuration, you make a GET request to the /v1/eventMessenger/subscriptionConfigurations/{id} resource.

Request path and header example

Copied to clipboard.

GET /v1/eventMessenger/subscriptionConfigurations/{id}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header and path parameters

Parameter	Located in	Description	Type	Required
`id`	Path	Unique ID of the subscription configuration. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.configuration.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the details of the specified subscription configuration. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
    "id": "amzn1.alexa.aem.subscription.configuration.123",
    "deliveryChannels": [{
        "type": "SNS",
        "id": "arn.aws.sns::12345:us-east1:abc"
    }]
}

Response body properties

Property	Description	Type
`id`	Unique ID of the subscription configuration. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.configuration.{id}`.	String
`deliveryChannels`	List of delivery mechanism configuration objects.	Array of objects
`deliveryChannels[].type`	Type of delivery channel. Valid values: `SNS`.	String
`deliveryChannels[].id`	Identifies the delivery channel. Set to the Amazon Resource Name (ARN) of the SNS topic to which to publish events.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the subscription configuration details.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. Retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List subscription configurations

Get a list of subscription configurations owned by the caller.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To get subscription configurations, you make a GET request to the /v1/eventMessenger/subscriptionConfigurations resource.

Request path and header example

Copied to clipboard.

GET /v1/eventMessenger/subscriptionConfigurations?owner={owner}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header and path parameters

Parameter	Located in	Description	Type	Required
`owner`	Query	Filter results to those subscription configurations associated with the owner. `~caller` represents the customer identified by the access token. Valid value: `~caller`	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–100. Default: 20.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response. If this token isn't present, the response contains the first page of results.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of subscription configurations owned by the caller. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
    "results": [{
          "id": "amzn1.alexa.aem.subscription.configuration.123",
          "deliveryChannels": [{
             "type": "SNS",
             "id": "arn.aws.sns::12345:us-east1:abc"
          }]
        },
        {
          "id": "amzn1.alexa.aem.subscription.configuration.456",
          "deliveryChannels": [{
             "type": "SNS",
             "identifier": "arn.aws.sns::12345:us-east1:abc"
          }]
        }
    ],
    "paginationContext": {
       "nextToken": someToken.1
    }
}

Response body properties

Property	Description	Type
`results`	List of subscription configurations owned by the caller.	Array of objects
`results[].id`	Unique ID of the subscription configuration. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.configuration.{id}`.	String
`results[].deliveryChannels`	List of delivery mechanism configuration objects.	Array of objects
`results[].deliveryChannels[].deliveryChannel.type`	Type of delivery channel. Valid values: `SNS`.	String
`results[].deliveryChannels[].deliveryChannel.id`	Identifies the delivery channel. Set to the Amazon Resource Name (ARN) of the SNS topic to which to publish events.	String
`paginationContext`	(Optional) Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the list of subscription configurations.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. Retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create subscription

Create a subscription that specifies the type of event you want to subscribe to and which subscription configuration to use. For a list of events, see Event Schemas.

Note: If you subscribe to receive skill fault events for a new skill and this operation returns HTTP 403 Forbidden, contact your Alexa Smart Properties solution architect to properly tag your skill for events.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To create a subscription, you make a POST request to the /v1/eventMessenger/subscriptions resource.

Request path and header example

Copied to clipboard.

POST /v1/eventMessenger/subscriptions
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header and path parameters

Parameter	Located in	Description	Type	Required
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "subscriptionConfigurationId": "amzn1.alexa.aem.subscription.configuration.123",
    "eventType": {
        "namespace": "Alexa.Automation.Execution",
        "name": "Completion"
    },
    "entities": {
        "unit": {
            "type": "Unit",
            "id": "amzn1.alexa.unit.did.101"
        }
    }
}

Request body properties

Property	Description	Type	Required
`subscriptionConfigurationId`	Unique ID of the subscription configuration to which to create the subscription. Returned in the Create subscription configuration response. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.configuration.{id}`.	String	Yes
`eventType`	Event details. For valid namespace and name combination, see Event Schemas.	Object	Yes
`eventType.namespace`	Represents the category to which an event belongs. All automation-related events share the same namespace. Example: `Alexa.Automation.Execution`.	String	Yes
`eventType.name`	Event name within the namespace. Example: `Completion`.	String	Yes
`entities`	Entities that define resources or experiences from which the event is generated, or which are directly related to the event. The entity provides additional context and metadata for the event that you can use for routing and access control. You can subscribe to receive events for entities that you create or own. For units, you can subscribe to events for units that you create. For skills, you can subscribe to receive events for skills that you own. For more details, see Resource entity, Skill entity, and Unit entity.	Object of entities	No

Response

A successful response returns HTTP 201 Created, along with the subscription ID. The response header also includes a link to the subscription ID in the Location parameter. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
  "id": "amzn1.alexa.aem.subscription.123"
}

Response body properties

Property	Description	Type
`id`	Unique ID of the subscription. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.{id}`.	String

HTTP status codes

Status	Description
`201 Created`	Subscription created successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete subscription

Deletes the specified subscription.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To delete a subscription, you make a DELETE request to the /v1/eventMessenger/subscriptions/{id} resource.

Request path and header example

Copied to clipboard.

DELETE /v1/eventMessenger/subscriptions/{id}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header and path parameters

Parameter	Located in	Description	Type	Required
`id`	Query	Unique ID of the subscription. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Subscription deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. Retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get subscription by ID

Gets the details of a the specified subscription.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To get a subscription, you make a GET request to the /v1/eventMessenger/subscriptions/{id} resource.

Request path and header example

Copied to clipboard.

GET /v1/eventMessenger/subscriptions/{id}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header and path parameters

Parameter	Located in	Description	Type	Required
`id`	Query	Unique ID of the subscription. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the details of the specified subscription. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
    "id": "amzn1.alexa.aem.subscription.123",
    "subscriptionConfigurationId": "amzn1.alexa.aem.subscription.configuration.123",
    "eventType": {
        "namespace": "Alexa.Automation.Execution",
        "name": "Completion"
    },
    "entities": {
        "unit": {
            "type": "Unit",
            "id": "amzn1.alexa.unit.did.101"
        }
    }
}

Response body properties

Property	Description	Type
`id`	Unique ID of the subscription. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.{id}`.	String
`subscriptionConfigurationId`	Unique ID of the subscription configuration. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.configuration.{id}`.	String
`eventType`	Event details. For valid namespace and name combination, see Event Schemas.	Object
`eventType.namespace`	Represents the category to which an event belongs. All automation-related events share the same namespace.	String
`eventType.name`	Event name within the namespace.	String
`entities`	Entities that define resources or experiences from which the event is generated, or which are directly related with the event. The entity provides additional context and metadata for the event that you can use for routing and access control. For more details, see Resource entity, Skill entity, and Unit entity.	Object of entities

HTTP status codes

Status	Description
`200 OK`	Response body contains the subscription details.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. Retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List subscriptions

Get a list of subscriptions owned by the caller.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To get subscriptions, you make a GET request to the /v1/eventMessenger/subscriptions resource.

Request path and header example

Copied to clipboard.

GET /v1/eventMessenger/subscriptions?owner={owner}&entities.unit.id={unitId}&entities.unit.type={entityType}&entities.unit.parent.id={parentId}&entities.unit.parent.type={parentType}&eventType.namespace={nameSpace}&eventType.names={name}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header and path parameters

Include one of the following sets of query parameters: owner, entities.unit.id and entities.unit.type, or entities.unit.parent.id and entities.unit.parent.type.

Parameter	Located in	Description	Type	Required
`owner`	Query	Filter results to those subscriptions with the owner. `~caller` represents the customer identified by the access token. Valid value: `~caller`	String	No
`unitId`	Query	Filter subscriptions to those associated with a particular unit. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`. If you include `entities.unit.id`, you must also include the `entities.unit.type` parameter.	String	No
`entityType`	Query	Filter subscriptions to those associated with a particular entity type. Valid value: `UNIT`. If you include `entities.unit.type`, you must also include the `entities.unit.id` parameter.	String	No
`parentId`	Query	Filter subscriptions to those associated with a particular parent unit. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`. If you include `entities.unit.parent.id`, you must also include the `entities.unit.parent.type` parameter.	String	No
`parentType`	Query	Filter subscriptions to those associated with a particular entity type. Valid value: `UNIT`. If you include `entities.unit.parent.type`, you must also include the `entities.unit.parent.id` parameter.	String	No.
`nameSpace`	Query	Filter subscriptions to those associated with a particular event namespace. If you include `eventType.namespace`, you must also include the `eventType.name` parameter. For valid namespace and name combination, see Event Schemas.	String	No
`name`	Query	Filter subscriptions to those associated with a particular event name. If you include `eventType.name`, you must also include the `eventType.namespace` parameter. For valid namespace and name combination, see Event Schemas.	String	No
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–100. Default: 20.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response. If this token isn't present, the response contains the first page of results.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of subscriptions. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
   "results": [{
       "id": "amzn1.alexa.aem.subscription.123",
       "subscriptionConfigurationId": "amzn1.alexa.aem.subscription.configuration.123",
       "eventType": {
           "namespace": "Alexa.Automation.Execution",
           "name": "Completion"
       },
       "entities": {
           "unit": {
               "type": "Unit",
               "id": "amzn1.alexa.unit.did.101"
           }
        }
     }
   ],
   "paginationContext": {
       "nextToken": null
   }
}

Response body properties

Property	Description	Type
`results`	List of subscription objects.	Array of objects
`results[].id`	Unique ID of the subscription. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.{id}`.	String
`results[].subscriptionConfigurationId`	Unique ID of the subscription configuration. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.aem.subscription.configuration.{id}`.	String
`results[].eventType`	Event details. For valid namespace and name combination, see Event Schemas.	Object
`results[].eventType.namespace`	Represents the category to which an event belongs. All automation-related events share the same namespace.	String
`results[].eventType.name`	Event name within the namespace.	String
`results[].entities`	Entities that define resources or experiences from which the event is generated, or which are directly related with the event. The entity provides additional context and metadata for the event that you can use for routing and access control. For more details, see Resource entity, Skill entity, and Unit entity.	Object of entities
`paginationContext`	(Optional) Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the list of subscriptions.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. Retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Object definitions

The Event Messenger API defines the following objects.

Error object

The Error object defines the error type and message included in the response when an error occurs.

The following example shows the response body.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

Property	Description	Type
`type`	Type of error that occurred. For specific error types, see the HTTP status code table for each operation.	String
`message`	Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String

Resource entity

Use the Resource entity for the following events:

Alexa.Role.Management.Assignment
Alexa.Role.Management.Revocation

Property	Description	Type	Required
`resource`	Resource details.	Object	Yes
`resource.type`	Type of entity. Valid value:`Resource`.	String	Yes
`resource.resourceType`	Type of resource. Valid value: `Unit`.	String	Yes
`resource.resourceId`	Unique identifier for the resource	String	Yes

Skill entity

Use the Skill entity for the following events:

Alexa.Skill.Interaction.Failure

Property	Description	Type	Required
`skill`	Details of the skill.	Object	No
`skill.type`	Type of entity. Valid value: `Skill`.	String	No
`skill.id`	Skill identifier. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.skill.did.{id}`. Valid values: 1 – 255 characters.	String	No

Unit entity

Use the Unit entity for the following events:

Alexa.Automation.Execution.Completion
Alexa.Skill.Interaction.Failure
Alexa.Enterprise.Subscription.Activation
Alexa.Endpoint.Lifecycle.SetupCompletion

Note: When you subscribe to an Enterprise subscription activation event, only specify the parent.

Property	Description	Type	Required
`unit`	Details of the unit.	Object	No
`unit.type`	Entity type. Valid value: `Unit`.	String	No
`unit.id`	Unit identifier. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String	No
`unit.parent`	Identifies the parent unit. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	Object	No

Was this page helpful?

Provide feedback

Last updated: Nov 26, 2024