Event Messenger API

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. See Get Started with Alexa Smart Properties APIs.

The Event Messenger API enables you to subscribe to receive Alexa events. 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. Currently, the only supported delivery channel for events is Amazon Simple Notification Service (SNS).

To use this API, you first create a subscription configuration, which defines a delivery channel that multiple subscriptions can use. You then create a subscription that specifies the type of event you want to subscribe to and which subscription configuration to use.

For details about how to use the Event Messenger API, see Receive Events for Alexa Smart Properties.

API endpoint

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

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

Authentication

Each API request must have an authorization header whose value is a Login with Amazon (LWA) access token.

Operations

The Event Messenger API includes the following operations.

Operation	HTTP Method and URI
Create a subscription configuration	`POST /v1/eventMessenger/subscriptionConfigurations`
Get a subscription configuration by ID	`GET /v1/eventMessenger/subscriptionConfigurations/{id}`
Get subscription configurations	`GET /v1/eventMessenger/subscriptionConfigurations`
Delete a subscription configuration	`DELETE /v1/eventMessenger/subscriptionConfigurations/{id}`
Create a subscription	`POST /v1/eventMessenger/subscriptions`
Get a subscription by ID	`GET /v1/eventMessenger/subscriptions/{id}`
Get subscriptions	`GET /v1/eventMessenger/subscriptions`
Delete subscription	`DELETE /v1/eventMessenger/subscriptions/{id}`

Create a subscription configuration

Creates 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 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	LWA access token.	String	Yes

Request body example

Copied to clipboard.

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

Request body parameters

Parameter	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`	Identifier of the channel the update is required on. Valid values: The Amazon Resource Name (ARN) of the SNS topic to which to publish events.	String enum	Yes

Response

A successful response returns HTTP 201 Created with the subscription configuration ID in the Location header.

Response body example

The following example shows the body of a successful response.

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

The following example shows the body of an error response.

{
    "type": "ERROR_TYPE",
    "message": "ERROR_MESSAGE"
}

Successful response body parameters

Parameter	Description	Type
`id`	Unique ID of the subscription configuration in UUID format.	String

Error response body parameters

Parameter	Description	Type
`type`	Type of error.	String
`message`	Description of the error.	String

HTTP status codes

Status	Description
`201 Created`	The subscription configuration was successfully created.
`400 Bad Request`	The request is invalid due to missing required fields, incorrect values, or malformed JSON.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because the client doesn't have permission to perform the operation.
`429 Too Many Requests`	The request was throttled. We recommend that you retry after one second, back off exponentially until a 256-second wait, and retry every 256 seconds thereafter until you receive a response that isn't 429.
`500 Internal Server Error`	A server-side error occurred.
`503 Unavailable`	The service is temporarily unavailable and couldn't accept the request.

Get a subscription configuration by ID

Gets 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 by configuration ID, you make a GET request to the /v1/eventMessenger/subscriptionConfigurations/{id} resource.

Request header example

Copied to clipboard.

GET /v1/eventMessenger/subscriptionConfigurations/amzn1.alexa.aem.subscription.configuration.123
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	LWA access token.	String	Yes
`id`	Query	Unique ID of the subscription configuration to get. This ID is returned by the Create a subscription configuration operation.	String	Yes

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 200 OK.

Response body example

The following example shows the body of a successful response.

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

The following example shows the body of an error response.

{
    "type": "ERROR_TYPE",
    "message": "ERROR_MESSAGE"
}

Successful response body parameters

Parameter	Description	Type
`id`	Unique ID of the subscription configuration in UUID format.	String
`deliveryChannels`	List of delivery mechanism configuration objects.	Array of objects
`deliveryChannels[*].type`	Type of delivery channel. Valid values: `SNS`.	String
`deliveryChannels[*].id`	Identifier of the channel the update is required on. Valid values: The Amazon Resource Name (ARN) of the SNS topic to which to publish events.	String enum

Error response body parameters

Parameter	Description	Type
`type`	Type of error.	String
`message`	Description of the error.	String

HTTP status codes

Status	Description
`200 OK`	The subscription configuration was successfully retrieved.
`400 Bad Request`	Invalid subscription configuration ID.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because the client doesn't have permission to perform the operation.
`404 Not Found`	The subscription configuration doesn't exist.
`429 Too Many Requests`	The request was throttled. We recommend that you retry after one second, back off exponentially until a 256-second wait, and retry every 256 seconds thereafter until you receive a response that isn't 429.
`500 Internal Server Error`	A server-side error occurred.
`503 Unavailable`	The service is temporarily unavailable and couldn't accept the request.

Get subscription configurations

Gets subscription configurations.

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 header example

Request subscription configurations by owner

Copied to clipboard.

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

Request that uses pagination

Copied to clipboard.

GET /v1/eventMessenger/subscriptionConfigurations?owner=~caller&nextToken=6666611111&maxResults=20
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	LWA access token.	String	Yes
`owner`	Query	A parameter that filters subscription configurations to only the subscriptions that the caller owns. The only value currently supported is `"~caller"`, which represents your information in the bearer token.	String	Yes
`nextToken`	Query	Token to retrieve a specific page of the paginated results. If this token isn't present, the response contains the first page of results.	String	No
`maxResults`	Query	Maximum number of results to return in the response body. This value must be greater than zero and less than or equal to 100. The default value is 20.	Number	No

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 200 OK.

Response body example

The following example shows the body of a successful response.

{
    "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": null
    }
}

The following example shows the body of an error response.

{
    "type": "ERROR_TYPE",
    "message": "ERROR_MESSAGE"
}

Successful response body parameters

Parameter	Description	Type
`results`	List of subscription configuration objects.	Array of objects
`results[*].id`	Unique ID of the subscription configuration in UUID format.	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`	Identifier of the channel the update is required on. Valid values: The Amazon Resource Name (ARN) of the SNS topic to which to publish events.	String enum
`paginationContext`	Pagination details.	Object
`paginationContext.nextToken`	Token to retrieve a specific page of the pagination results.	String

Error response body parameters

Parameter	Description	Type
`type`	Type of error.	String
`message`	Description of the error.	String

HTTP status codes

Status	Description
`200 OK`	The subscription configurations were successfully retrieved.
`400 Bad Request`	The request is invalid due to missing required fields, incorrect values, or malformed JSON.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because the client doesn't have permission to perform the operation.
`429 Too Many Requests`	The request was throttled. We recommend that you retry after one second, back off exponentially until a 256-second wait, and retry every 256 seconds thereafter until you receive a response that isn't 429.
`500 Internal Server Error`	A server-side error occurred.
`503 Unavailable`	The service is temporarily unavailable and couldn't accept the request.

Delete a subscription configuration

Deletes a 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 header example

Copied to clipboard.

DELETE /v1/eventMessenger/subscriptionConfigurations/amzn1.alexa.aem.subscription.configuration.123
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	LWA access token.	String	Yes
`id`	Query	Unique ID of the subscription configuration to delete. This ID is returned by the Create a subscription configuration operation.	String	Yes

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 204 No Content.

Response body example

A successful response has no body.

The following example shows the body of an error response.

{
    "type": "ERROR_TYPE",
    "message": "ERROR_MESSAGE"
}

Successful response body parameters

A successful response has no body.

Error response body parameters

Parameter	Description	Type
`type`	Type of error.	String
`message`	Description of the error.	String

HTTP status codes

Status	Description
`204 No Content`	The request was successfully processed.
`400 Bad Request`	The subscription configuration ID is invalid.
`400 Invalid Config ID`	The subscription configuration can't be deleted because it has one or more subscriptions associated with it.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because the client doesn't have permission to perform the operation.
`404 Not Found`	The subscription configuration doesn't exist.
`429 Too Many Requests`	The request was throttled. We recommend that you retry after one second, back off exponentially until a 256-second wait, and retry every 256 seconds thereafter until you receive a response that isn't 429.
`500 Internal Server Error`	A server-side error occurred.
`503 Unavailable`	The service is temporarily unavailable and couldn't accept the request.

Create a subscription

Creates a subscription, which specifies the type of event you want to subscribe to and which subscription configuration to use.

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 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	LWA access 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.{id}"
        }
    }
}

Request body parameters

Parameter	Description	Type	Required
`subscriptionConfigurationId`	Configuration ID of the subscription configuration created by using Create a subscription configuration.	String	Yes
`eventType`	Object that contains event details.	Object	Yes
`eventType.namespace`	Represents the category an event belongs to. All automation-related events share the same namespace. Example: `Alexa.Automation.Execution`	String	Yes
`eventType.name`	An 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 with the event. The entity provides additional context and metadata for the event that you can use for routing and access control. You can only subscribe to receive events for entities that you create or own. This means that for units, you can only subscribe to events for units that you create. For skills, you can only subscribe to receive events for skills that you own.	Object of entities. For details, see Unit entity and Skill entity.	No

Unit entity

The unit entity is required 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.

Parameter	Description	Type	Required
`unit`	Object that represents the details of a unit.	Object	No
`unit.type`	Unit entity type. Valid values: `Unit`	String enum	No
`unit.id`	Unit identifier	String	No
`unit.parent`	Parent unit, which contains the parent ID.	Object	No

Resource entity

The Resource entity is required for the following events:

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

Parameter	Description	Type	Required
`resource`	Object that represents the details of the resource.	Object	Yes
`resource.type`	Resource entity type. Valid values: "Resource"	String	Yes
`resource.resourceType`	The type of the resource. Valid value: "Unit"	String	Yes
`resource.resourceId`	The unique identifier for the resource	String	Yes

Skill entity

The skill entity is required for the following events:

Alexa.Skill.Interaction.Failure

Parameter	Description	Type	Required
`skill`	Object that represents the details of a skill.	Object	No
`skill.type`	Skill entity type. Valid values: `Skill`	String enum	No
`skill.id`	Skill identifier	String	No

Response

A successful response returns HTTP 201 Created with the subscription ID in the Location header.

Response body example

The following example shows the body of a successful response.

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

The following example shows the body of an error response.

{
    "type": "ERROR_TYPE",
    "message": "ERROR_MESSAGE"
}

Successful response body parameters

Parameter	Description	Type
`id`	Unique subscription ID in UUID format.	String

Error response body parameters

Parameter	Description	Type
`type`	Type of error.	String
`message`	Description of the error.	String

HTTP status codes

Status	Description
`201 Created`	The subscription was successfully created.
`400 Bad Request`	Invalid subscription configuration ID.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because the client doesn't have permission to perform the operation. If you are subscribing to receive skill fault events for a skill that is new, we might not have that skill tagged for events, which will generate a 403 error. In this case, reach out to your solution architect to properly tag your skill.
`429 Too Many Requests`	The request was throttled. We recommend that you retry after one second, back off exponentially until a 256-second wait, and retry every 256 seconds thereafter until you receive a response that isn't 429.
`500 Internal Server Error`	A server-side error occurred.
`503 Unavailable`	The service is temporarily unavailable and couldn't accept the request.

Get a subscription by ID

Gets a subscription by subscription ID.

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 header example

Copied to clipboard.

GET /v1/eventMessenger/subscriptions/amzn1.alexa.aem.subscription.123
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	LWA access token.	String	Yes
`id`	Query	Unique ID of the subscription to get.	String	Yes

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 200 OK.

Response body example

The following example shows the body of a successful response.

{
    "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.{id}"
        }
    }
}

The following example shows the body of an error response.

{
    "type": "ERROR_TYPE",
    "message": "ERROR_MESSAGE"
}

Successful response body parameters

Parameter	Description	Type
`id`	Unique subscription ID in UUID format.	String
`subscriptionConfigurationId`	Configuration ID of the subscription configuration created by using Create a subscription configuration.	String
`eventType`	Object that contains event details.	Object
`eventType.namespace`	Represents the category an event belongs to. All automation-related events share the same namespace. Example: `Alexa.Automation.Execution`	String
`eventType.name`	An event name within the namespace. Example: `Completion`	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.	Object of entities. For details, see Unit entity and Skill entity.

Error response body parameters

Parameter	Description	Type
`type`	Type of error.	String
`message`	Description of the error.	String

HTTP status codes

Status	Description
`200 OK`	The subscription was successfully retrieved.
`400 Bad Request`	The subscription ID is invalid.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because the client doesn't have permission to perform the operation.
`404 Not Found`	The subscription doesn't exist.
`429 Too Many Requests`	The request was throttled. We recommend that you retry after one second, back off exponentially until a 256-second wait, and retry every 256 seconds thereafter until you receive a response that isn't 429.
`500 Internal Server Error`	A server-side error occurred.
`503 Unavailable`	The service is temporarily unavailable and couldn't accept the request.

Get subscriptions

Gets subscriptions.

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 header example

Request subscriptions by owner

Copied to clipboard.

GET /v1/eventMessenger/subscriptions?owner=~caller
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request subscriptions by entities.unit.id and entities.unit.type

Copied to clipboard.

GET /v1/eventMessenger/subscriptions?owner=~caller&entities.unit.id=amzn1.alexa.unit.did.123&entities.unit.type=Unit
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request that uses pagination

Copied to clipboard.

GET /v1/eventMessenger/subscriptions?owner=~caller&nextToken=6666611111&maxResults=20
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	LWA access token.	String	Yes
`owner`	Query	A parameter that filters subscriptions to only the subscriptions that the caller owns. The only value currently supported is `"~caller"`, which represents your information in the bearer token.	String	Yes
`entities.unit.id`	Query	A parameter that filters subscriptions to only those that are associated with a particular `unitId`. If you include this parameter, you must also include the `entities.unit.type` parameter. Either `owner` or (`entities.unit.id && entities.unit.type`) or (`entities.unit.parent.id && entities.unit.parent.type`) is required.	String	No. See description.
`entities.unit.type`	Query	A parameter that filter subscriptions to only those that are associated with a particular `unitType`. If you include this parameter, you must also include the `entities.unit.id` parameter. Either `owner` or (`entities.unit.id && entities.unit.type`) or (`entities.unit.parent.id && entities.unit.parent.type`) is required.	String	No. See description.
`entities.unit.parent.id`	Query	A parameter that filters subscriptions to only those that are associated with a particular parent `unitId`. If you include this parameter, you must also include the `entities.parent.type` parameter. Either `owner` or (`entities.unit.id && entities.unit.type`) or (`entities.unit.parent.id && entities.unit.parent.type`) is required.	String	No. See description.
`entities.unit.parent.type`	Query	A parameter that filters subscriptions to only those that are associated with a particular parent `unitType`. If you include this parameter, you must also include the `entities.parent.id` parameter. Either `owner` or (`entities.unit.id && entities.unit.type`) or (`entities.unit.parent.id && entities.unit.parent.type`) is required.	String	No. See description.
`eventType.namespace`	Query	A parameter that filters subscriptions to only those that are associated with a particular `eventType` namespace. If you include this parameter, you must also include the `eventType.name` parameter.	String	No
`eventType.name`	Query	A parameter that filters subscriptions to only those that are associated with a particular `eventType` name. If you include this parameter, you must also include the `eventType.namespace` parameter.	String	No
`nextToken`	Query	Token to retrieve a specific page of the paginated results. If this token isn't present, the response contains the first page of results.	String	No
`maxResults`	Query	Maximum number of results to return in the response body. This value must be greater than zero and less than or equal to 100. The default value is 20.	Number	No

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 200 OK.

Response body example

The following example shows the body of a successful response.

{
   "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.{id}"
           }
        }
     }
   ],
   "paginationContext": {
       "nextToken": null
   }
}

The following example shows the body of an error response.

{
    "type": "ERROR_TYPE",
    "message": "ERROR_MESSAGE"
}

Successful response body parameters

Parameter	Description	Type
`paginationContext`	Pagination details.	Object
`paginationContext.nextToken`	Token to retrieve a specific page of the pagination results.	String
`results`	List of subscription objects.	Array of objects
`results.id`	Unique subscription ID in UUID format.	String
`results.subscriptionConfigurationId`	Configuration ID of the subscription configuration created by using Create a subscription configuration.	String
`results.eventType`	Object that contains event details.	Object
`results.eventType.namespace`	Represents the category an event belongs to. All automation-related events share the same namespace. Example: `Alexa.Automation.Execution`	String
`results.eventType.name`	An event name within the namespace. Example: `Completion`	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.	Object of entities. For details, see Unit entity and Skill entity.

Error response body parameters

Parameter	Description	Type
`type`	Type of error.	String
`message`	Description of the error.	String

HTTP status codes

Status	Description
`200 OK`	The subscriptions were successfully retrieved.
`400 Bad Request`	Invalid subscription ID.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because the client doesn't have permission to perform the operation.
`404 Not Found`	The subscription doesn't exist.
`429 Too Many Requests`	The request was throttled. We recommend that you retry after one second, back off exponentially until a 256-second wait, and retry every 256 seconds thereafter until you receive a response that isn't 429.
`500 Internal Server Error`	A server-side error occurred.
`503 Unavailable`	The service is temporarily unavailable and couldn't accept the request.

Delete subscription

Deletes a 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 header example

Copied to clipboard.

DELETE /v1/eventMessenger/subscriptions/amzn1.alexa.aem.subscription.123
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	LWA access token.	String	Yes
`id`	Query	Unique ID of the subscription to delete.	String	Yes

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 204 No Content.

Response body example

A successful response has no body.

The following example shows the body of an error response.

{
    "type": "ERROR_TYPE",
    "message": "ERROR_MESSAGE"
}

Successful response body parameters

A successful response has no body.

Error response body parameters

Parameter	Description	Type
`type`	Type of error.	String
`message`	Description of the error.	String

HTTP status codes

Status	Description
`204 No Content`	The request was successfully processed.
`400 Bad Request`	Invalid subscription ID.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because the client doesn't have permission to perform the operation.
`404 Not Found`	The subscription doesn't exist.
`429 Too Many Requests`	The request was throttled. We recommend that you retry after one second, back off exponentially until a 256-second wait, and retry every 256 seconds thereafter until you receive a response that isn't 429.
`500 Internal Server Error`	A server-side error occurred.
`503 Unavailable`	The service is temporarily unavailable and couldn't accept the request.

Was this page helpful?

Provide feedback

Last updated: Dec 13, 2023