Use Skill Events

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

When you subscribe to skill events, Alexa notifies your skill when an event occurs. Your skill receives an event when a customer enables or disables the skill, links or unlinks a third-party account with the skill, grants permissions to a skill, or changes the permissions granted to the skill.

All skill models, including custom skills and smart home skills, support skill events.

Permissions to access specified customer data are granted at the skill level, and there are no event-specific permissions.

Prerequisites to Use Events in Your Skill Service

To use events in your skill service, you must set up access to the Alexa Skill Management API (SMAPI) as described in Add Events to Your Skill With SMAPI. If you use SMAPI, you must develop your skill using ASK CLI (Alexa Skills Kit Command Line Interface), because some features supported in SMAPI are not supported on the Amazon Developer Portal. The skill events feature is one of them. Thus, if you set up your skill to consume skill events, it can only be managed with ASK CLI, and not with the Amazon Developer Portal.

As the developer, your skill manifest must meet these requirements in order to manage events in the skill:

You must set up your skill to prompt the customer to grant the appropriate permissions. Your skill.json file requires a permissions object if you include list events in your skill manifest, as described in Update your skill definition to include events.
Your skill manifest must include an events object which includes your subscriptions to events, as seen in the Skill Manifest.
You must ensure that your AWS Lambda function endpoint is configured with an Alexa Skills Kit trigger. You can do this in the AWS Console, as described here.

To obtain a customer consent token from an out-of-session interaction with the Skill Messaging API, see Out of Session Interaction.

To send a message request to a skill for a specified user, refer to Send a Message Request to a Skill.

Although many of the following events show an accessToken field, note that accessToken is not present if the customer has not linked their Alexa account to the appropriate third-party app.

However, the skill developer should not rely on the access token being present except as obtained through the account linking event. The skill service should store the relation between the Alexa user id and the 3P user id when it receives the access token in the account linking event.

Similarly, the permissions object, which contains the consentToken field, if the customer has granted permissions to the skill, is added to the user object for events, but is otherwise not present. If the consentToken field is null, the permissions object is not present.

Event creation and publishing fields

For all skill events that include a timestamp, eventCreationTime, or eventPublishingTime field, the format is UTC: YYYY-MM-DD'T'hh:mm:ss'Z'. The timestamp field is now deprecated in favor of eventCreationTime." Use eventPublishingTime to verify if the request was sent no later than 150 seconds since the original published time.

Out-of-Session Interaction

Your app can request an out-of-session access token when it needs to access the skill outside of the customer's voice request, following these steps:

Obtain the Skill Messaging API access token, using the ClientId and ClientSecret as inputs. To get these ClientId and ClientSecret values, refer to the Configuration tab for your skill in the Amazon Developer Portal. See the request format in Configure an Application or Service to Send Messages to Your Skill. If your skill has been managed through SMAPI, you can still see these values in the developer portal. Go to the list of skills. Those skills that have the appropriate permissions will show the link View Skill ID and Client Secret. When you click this link, the Skill ID, Client ID, and Client Secret appear in a popup.
Once the access token is obtained, the app makes an asynchronous call to the Skill Messaging API using the Skill Messaging API access token and the userId value, which was obtained during an earlier customer voice interaction. The Skill Messaging API calls the skill back with the customer consent token.

See: Skill Messaging API

Delivery of Events to the Skill

Alexa will attempt to redeliver events if an acknowledgement is not sent by the skill service, for up to one hour. If the skill service receives an event, and the skill service sends an acknowledgment in response, this event must then be managed by the skill service. In either case, the skill service cannot, at a later time, retrieve past events from Alexa.

Order of Event Arrival to the Skill

Skill events are sent to the skill, but the order in which the skill receives these events is not necessarily the same as when they occurred.

Thus, any action that the skill takes as a result of an event should consider the eventCreationTime of the event. For example, if a skill is enabled and then disabled, resulting in a skill enabled event and a skill disabled event, and the skill disabled event arrives to the skill before the skill enabled event, the skill service should not act as if the skill is enabled.

Skill Events in JSON Format

The following sections list the JSON format for each skill event. As mentioned, the accessToken field and the permissions object are not present except in the cases mentioned in in the previous section. In each case, the event includes the appropriate apiEndpoint value for the region.

Account Linked Event

The account-linked event indicates that a customer linked their Alexa app with an account in your system. This event is useful for applications that support out-of-session (non-voice) user interactions. Because this event is triggered by account linking, this event notifies your application when you can associate the skill user's Amazon identity with their identity in your system.

Note: This event is required for many applications that synchronize customer Alexa lists with application lists.

During the account-linking process, the Alexa app directs the user to your skill's website, where the customer logs in. When the customer logs in, the skill then provides an access token and a consent token to Alexa. The event includes the same access token and consent token.

Version 1.1 of this event supports personalization (the person object).

v1.1
v1.0

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string",
        "accessToken": "string",
        "permissions": {
          "consentToken": "string"
        }
      },
      "person": {
          "personId": "string",
          "accessToken": "string"
        },
        "apiEndpoint": "https://api.amazonalexa.com",
        "apiAccessToken": "string"
      }
    },
    "request": {
      "type": "AlexaSkillEvent.SkillAccountLinked",
      "requestId": "string in the form alexa.skill.event.UUID",
      "body": {
        "accessToken": "string"
      },
      "timestamp": "string",
      "eventCreationTime": "string",
      "eventPublishingTime": "string"
    }
  }

  {
    "version": "string",
    "context": {
      "System": {
        "application": {
          "applicationId": "string"
        },
        "user": {
          "userId": "string",
          "accessToken": "string",
          "permissions": {
            "consentToken": "string"
          }
        },
        "apiEndpoint": "https://api.amazonalexa.com",
        "apiAccessToken": "string"
      }
    },
    "request": {
      "type": "AlexaSkillEvent.SkillAccountLinked",
      "requestId": "string in the form alexa.skill.event.UUID",
      "body": {
        "accessToken": "string"
      },
      "timestamp": "string",
      "eventCreationTime": "string",
      "eventPublishingTime": "string"
    }
  }

Account Unlinked Event

The account-unlinked event indicates that a customer unlinked their Alexa app with their account in your system.

Version 1.1 of this event supports personalization (the person object).

Note: Skills can receive the account-unlinked event only if personalization is enabled.

v1.1

{
    "version": "string",
    "context": {
        "System": {
            "application": {
                "applicationId": "string"
            },
            "user": {
                "userId": "string",
                "permissions": {
                    "consentToken": "string"
                }
            },
            "person": {
                "personId": "string"
            },
            "apiEndpoint": "https://api.amazonalexa.com",
            "apiAccessToken": "string"
        }
    },
    "request": {
        "type": "AlexaSkillEvent.SkillAccountUnlinked",
        "requestId": "string in the form alexa.skill.event.UUID",
        "timestamp": "string",
        "eventCreationTime": "string",
        "eventPublishingTime": "string"
    }
}

Skill Enabled Event

This event is sent when a customer enables the skill. Skill enablement works at the account level. Therefore, events don't contain the person object, even if personalization is enabled.

v1.0

  {
    "version": "string",
    "context": {
      "System": {
        "application": {
          "applicationId": "string"
        },
        "user": {
          "userId": "string"
        },
        "apiEndpoint": "https://api.amazonalexa.com",
        "apiAccessToken": "string"
      }
    },
    "request": {
      "type": "AlexaSkillEvent.SkillEnabled",
      "requestId": "string in the form alexa.skill.event.UUID",
      "timestamp": "string",		
      "eventCreationTime": "string",
      "eventPublishingTime": "string"
    }
  }

Skill Disabled Event

This event is sent when a customer disables the skill. When a skill is disabled, a skill permission changed event is not sent, although implicitly permission is revoked as part of disabling the skill. The skill service should handle this skill disabled event. Note that a SkillDisabled event contains only userId and no access token, because the access token is removed from Amazon systems whenever a customer disables the skill.

Skill disablement works at the account level. Therefore, events don't contain the person object, even if personalization is enabled.

v1.0

  {
    "version": "string",
    "context": {
      "System": {
        "application": {
          "applicationId": "string"
        },
        "user": {
          "userId": "string"
        },
        "apiEndpoint": "https://api.amazonalexa.com",
        "apiAccessToken": "string"
      }
    },
    "request": {
      "type": "AlexaSkillEvent.SkillDisabled",
      "requestId": "string in the form alexa.skill.event.UUID",
      "timestamp": "string",		
      "eventCreationTime": "string",
      "eventPublishingTime": "string",
      "body": {
        "userInformationPersistenceStatus": "PERSISTED"
      }
    }
  }

The userInformationPersistenceStatus indicates whether it is safe to delete the data you have saved for this user in your own persistent storage:

PERSISTED: If the user re-enables the skill, they will get the same userId, so do not clear their data.
NOT_PERSISTED: If the user re-enables the skill, they will get a new userId. Therefore, it is safe to clear data you have stored with the userId.

For example, userInformationPersistenceStatus is PERSISTED if the skill offers consumable purchases. In this case, you would retain the consumable product inventory associated with the userId.

Skill Permission Accepted Event

This event is sent when a customer (or person, for v1.1) accepts permissions the first time, or grants permissions after revoking all the permissions. Skill permissions events for changing or granting permissions always include the most recently accepted permissions in the payload. Version 1.1 of this event supports personalization (the person object).

The accessToken field is present if the customer has linked their Alexa account to the appropriate third-party app.

v1.1
v1.0

The acceptedPersonPermissions field is present if the person object is present.

{
  "version": "1.1",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string",
        "accessToken": "string",
        "permissions":{
          "consentToken":"string"
        }
      },
      "person": {
        "personId": "string",
        "accessToken": "string"
      },      
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "string"      
    }
  },
  "request": {
    "type": "AlexaSkillEvent.SkillPermissionAccepted",
    "requestId": "string",
    "timestamp": "string",  
    "eventCreationTime": "string",
    "eventPublishingTime": "string",
    "body": {
      "acceptedPermissions":  [{
          "scope": "string"
      }],
      "acceptedPersonPermissions":  [{
          "scope": "string"
      }]      
    }
  }
}

{
  "version": "v1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string",
        "accessToken": "string",
        "permissions":{
          "consentToken":"string"
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "string"        
    }
  },
  "request": {
    "type": "AlexaSkillEvent.SkillPermissionAccepted",
    "requestId": "string",
    "timestamp": "string",  
    "eventCreationTime": "string",
    "eventPublishingTime": "string",
    "body": {
      "acceptedPermissions":  [{
          "scope": "string"
      }]
    }
  }
}

Skill Permission Changed Event

This event is sent if a customer (or person, for v1.1) grants additional permissions to a skill, or revokes the existing permissions to a skill. Skill permissions events for changing or granting permissions always include the most recently accepted permissions in the payload. Version 1.1 of this event supports personalization (the person object).