Skill Events in Alexa Skills
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.
See also: List Events
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 apermissions
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.For a demo that shows how to configure event subscriptions in a skill manifest, see the Delete Persistent Attributes Demo in the alexa-cookbook repo on GitHub.
-
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.
Access Tokens, Permissions, and Consent Tokens in Events
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
andClientSecret
as inputs. To get theseClientId
andClientSecret
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.
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).
{
"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"
}
}
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.
{
"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.
{
"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 sameuserId
, so do not clear their data.NOT_PERSISTED
: If the user re-enables the skill, they will get a newuserId
. Therefore, it is safe to clear data you have stored with theuserId
.
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.
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).
The accessToken
field is present if the customer has linked their Alexa account to the appropriate third-party app.
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.SkillPermissionChanged",
"requestId": "string",
"timestamp": "string",
"eventCreationTime": "string",
"eventPublishingTime": "string",
"body": {
"acceptedPermissions": [{
"scope": "string"
}],
"acceptedPersonPermissions": [{
"scope": "string"
}]
}
}
}
{
"version": "1.0",
"context": {
"System": {
"application": {
"applicationId": "string"
},
"user": {
"userId": "string",
"accessToken": "string",
"permissions":{
"consentToken":"string"
}
},
"apiEndpoint": "https://api.amazonalexa.com",
"apiAccessToken": "string"
}
},
"request": {
"type": "AlexaSkillEvent.SkillPermissionChanged",
"requestId": "string",
"timestamp": "string",
"eventCreationTime": "string",
"eventPublishingTime": "string",
"body": {
"acceptedPermissions": [{
"scope": "string"
}]
}
}
}
Last updated: Sep 29, 2022