Event Schemas for Alexa Smart Properties Core

Alexa Smart Properties enables you to receive notifications about Alexa events. Events are published to Amazon Simple Notification Service (SNS).

For details about how to set up events, see Receive Events for Alexa Smart Properties Core.

Event types

The following table contains the Alexa Smart Properties events to which you can subscribe to receive notifications.

Event Name Description Schema

Alexa.Automation.Execution.Completion

An automation sequence execution is complete. Either all actions are invoked and completed successfully, or there were failures.

Automation execution completion event

Alexa.Skill.Interaction.Failure

The skill times out or the skill returns an invalid response.

Skill interaction failure event

Alexa.Enterprise.Subscription.Activation

An enterprise subscription is activated for a unit.

Enterprise subscription activation

Automation execution completion event

The following is an example of an automation execution completion event.

{
   "header":{
      "version":"2.0",
      "eventId":{
         "id":"12345-6789-1011-abcd-example"
      },
      "eventType":{
         "namespace":"Alexa.Automation.Execution",
         "name":"Completion"
      },
      "eventTime":{
         "timestamp":"2017-09-20T12:04:03Z"
      },
      "entities": {
         "unit":{
            "type":"Unit",
            "id":"amzn1.alexa.unit.did.12345"
         }
      }
   },
   "payload":{
      "automation":{
         "id":"amzn1.alexa.automation.12345"
      },
      "result": {
        "status": "FAILURE",
      	"errors":[
         {
            "type":"ENDPOINT_NOT_FOUND",
            "message":"Endpoint used in the automation was not found",
            "id":"amzn1.alexa.endpoint.12345"
         }
       ]
     }
   }
}

Header parameters

Parameter Description Type Required

header.version

Schema version, which is 2.0.

String

Yes

header.eventId

Object that contains the event ID.

Object

Yes

header.eventId.id

Unique identifier that represents an event.

String

Yes

header.eventType

Object that contains the event name and namespace.

Object

Yes

header.eventType.namespace

Represents the category an event belongs to. All automation-related events share the same namespace. Example: Alexa.Automation.Execution

String

Yes

header.eventType.name

An event name within the namespace. Example: Completion

String

Yes

eventTime

Object that contains the event time.

Object

Yes

eventTime.timestamp

Event creation time in "YYYY-MM-DDThh:mm:ssZ" format (RFC 3339 profile of ISO 8601).

DateTime

Yes

entities

List of entities. For details, see Unit entity.

Array

Yes

Payload parameters

Parameter Description Type Required

payload.automation

Details for the automation from which the event was generated.

Object

types

payload.automation.id

Unique identifier of the automation instance from which the event was generated.

String

Yes

payload.result

Details about the result of the automation.

Object

Yes

payload.result.status

Status of automation execution initiation or completion. Allowed values:
  • SUCCESS: Automation was triggered and completed successfully.
  • FAILURE: Automation trigger or completion failed.

String enum

Yes

payload.result.errors

Errors that occurred for automation initiation or completion.

Array

No

payload.result.errors[*].type

Error type. Allowed values:
  • ENDPOINT_NOT_FOUND: Endpoint used in the automation wasn't found.
  • INTERNAL_SERVER_ERROR: Internal server error.

String

No

payload.result.errors[*].message

Message that describes the error.

String

No

payload.result.errors[*].id

Endpoint ID. Example: amzn1.alexa.endpoint.12345

String

No

Skill interaction failure event

The following is an example of a skill interaction event that reports a skill fault event due to an invalid response from the skill or a skill endpoint timeout.

{
   "header":{
      "version":"2.0",     
      "eventId":{
         "id":"12345-6789-1011-abcd-example"
      },
      "eventType":{
         "namespace":"Alexa.Skill.Interaction",
         "name":"Failure"
      },
      "eventTime":{
         "timestamp":"2017-09-20T12:04:03Z"
      },
      "entities": {
         "unit":{
            "type":"Unit",
            "id":"amzn1.alexa.unit.did.12345"
         },
         "skill":{
            "type":"Skill",
            "id":"amzn1.ask.skill.12345"
         }         
      }
   },
   "payload":{
      "interaction":{
         "type":"IntentRequest",
         "locale":"en-US",
         "intent":{
            "name":"intentName"
         },
      },
      "skill":{
         "id":"amzn1.ask.skill.12345",
         "stage":"live"
      },
      "unit":{
         "id":"amzn1.alexa.unit.did.12345"
      },
      "session":{
         "id":"amzn1.echo-api.session.12345"
      },
      "requestId":"amzn1.echo-api.request.12345",
      "error":{
         "type":"INVALID_RESPONSE",
         "message":"Details about the error"
      }
   }
}

Header parameters

Parameter Description Type Required

header.version

Schema version, which is 2.0.

String

Yes

header.eventId

Object that contains the event ID.

Object

Yes

header.eventId.id

Unique identifier that represents an event.

String

Yes

header.eventType

Object that contains the event name and namespace.

Object

Yes

header.eventType.namespace

Represents the category an event belongs to. All skill interaction-related events share the same namespace. Example: Alexa.Skill.Interaction

String

Yes

header.eventType.name

An event name within the namespace. Example: Failure

String

Yes

eventTime

Object that contains the event time.

Object

Yes

eventTime.timestamp

Event creation time in "YYYY-MM-DDThh:mm:ssZ" format (RFC 3339 profile of ISO 8601).

DateTime

Yes

entities

List of entities. For details, see Unit entity and Skill entity.

Array

Yes

Payload parameters

Parameter Description Type Required

payload.interaction

Object that describes the type of skill interaction where failures were observed.

Object

Yes

payload.interaction.type

Type of skill interaction where failures were observed. Allowed values: IntentRequest

String enum

Yes

payload.interaction.locale

User's locale. Example: en-US

String

Yes

payload.interaction.intent

Object that indicates the action that fulfills a user's spoken request.

Object

No

payload.interaction.intent.name

Name of the intent that corresponds to the action the user requested. Example: AMAZON.CancelIntent

String

No

payload.skill

Object that represents the skill to which the event pertains.

Object

Yes

payload.skill.id

Unique identifier of a skill. Example: amzn1.ask.skill.12345

String

Yes

payload.skill.stage

Stage of the skill. Allowed values: development, live, or certification

String

Yes

payload.unit

Object that contains the unit ID.

Object

Yes

payload.unit.id

Unit ID that uniquely identifies a unit.

String

Yes

payload.session

Object that contains an ID that uniquely identifies a skill session.

Object

Yes

payload.session.id

ID that uniquely identifies a skill session. Example: amzn1.echo-api.session.12345. This value might be a session ID you haven't seen before, such as when the first request to a skill fails to reach the skill.

String

Yes

payload.requestId

ID that uniquely identifies an Alexa user request and the response to it. Example: amzn1.echo-api.request.12345-678910-abcdefg

String

Yes

payload.error

Object that contains additional details about the result of the user's request to the skill.

Object

Yes

payload.error.type

Type of error. Allowed values:
  • INVALID_RESPONSE: This can happen when Alexa is unable to understand the skill response (for example, the SSML format in the skill response is invalid) or when Alexa is unable to call the endpoint for some reason (for example, the endpoint is misconfigured, Alexa doesn't have the required permissions, and so on).
  • ENDPOINT_TIMEOUT: Alexa didn't get a response in time.

String enum

Yes

payload.error.message

Description of the error. You should rely on the type of error and not the message of the error. The message is only used for logging purposes.

String

Yes

Enterprise subscription activation event

The following is an example of an enterprise subscription activation event.

{
   "header":{
      "version":"2.0",     
      "eventId":{
         "id":"12345-6789-1011-abcd-example"
      },
      "eventType":{
         "namespace":"Alexa.Enterprise.Subscription",
         "name":"Activation"
      },
      "eventTime":{
         "timestamp":"2017-09-20T12:04:03Z"
      },
      "entities": {
         "unit":{
            "type":"Unit",
            "id":"amzn1.alexa.unit.did.12345",
            "parent": {
               "type":"Unit",
               "id":"amzn1.alexa.unit.did.12345"
            }
         }
      }
   },
   "payload":{        
      "subscription": {
         "id": "amzn1.ask.skill.12345"
      },
      "result": {
         "status": "SUCCEEDED",
         "error": {
            "type": "INTERNAL_SERVER_ERROR",
            "message": "Details about the error"
         }
      }    
   }
}

Header parameters

Parameter Description Type Required

header.version

Schema version, which is 2.0.

String

Yes

header.eventId

Object that contains the event ID.

Object

Yes

header.eventId.id

Unique identifier that represents an event.

String

Yes

header.eventType

Object that contains the event name and namespace.

Object

Yes

header.eventType.namespace

Represents the category an event belongs to. All enterprise subscription-related events share the same namespace. Example: Alexa.Enterprise.Subscription

String

Yes

header.eventType.name

An event name within the namespace. Example: Activation

String

Yes

eventTime

Object that contains the event time.

Object

Yes

eventTime.timestamp

Event creation time in "YYYY-MM-DDThh:mm:ssZ" format (RFC 3339 profile of ISO 8601).

DateTime

Yes

entities

List of entities. For details, see Unit entity.

Array

Yes

Payload parameters

Parameter Description Type Required

payload.subscription

Details of the subscription for which the event was generated.

Object

Yes

payload.subscription.id

ID of the subscription.

String enum

Yes

payload.result

Result of the subscription activation.

Object

Yes

payload.result.status

Status of the subscription activation.

String enum

Yes

payload.result.error

Error that occurred for subscription activation. If activation succeeds, this object won't be present.

Object

No

payload.error.type

Type of error. Allowed values:
  • INTERNAL_SERVER_ERROR: The activation workflow timed out or failed to run.

String enum

Yes

payload.error.message

Description of the error. You should rely on the type of error and not the message of the error. The message is only used for logging purposes.

String

Yes

Entities

The header of the event can have the following entities.

Unit entity

Parameter Description Type Required

unit

Object that represents the details of a unit.

Object

Yes

unit.type

Unit entity type. Valid values: Unit

String enum

Yes

unit.id

Unit identifier.

String

Yes

unit.parent

Parent unit, which contains the parent ID.

Object

Yes

unit.parent.type

Parent entity type. Valid values: Unit

String enum

Yes

unit.parent.id

Parent identifier.

String

Yes

Skill entity

Parameter Description Type Required

skill

Object that represents the details of a skill.

Object

Yes

skill.type

Skill entity type. Valid values: Skill

String enum

Yes

skill.id

Skill identifier.

String

Yes