Use Skill Events

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

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

Amazon grants permission to access specified customer data at the skill level, and there are no event-specific permissions.

Prerequisites to use events in your skill

To use events in your skill, add events to your skill manifest. If you use events, you must develop your skill with the ASK CLI (Alexa Skills Kit Command Line Interface) because the skill events feature isn't supported in the Alexa developer console. Thus, if you set up your skill to consume skill events, you manage the events with the ASK CLI, and not with the developer console.

Your skill manifest must meet the following requirements to manage events in your skill:

  • Configure your skill to prompt the customer to grant the appropriate permissions. If necessary for your skill, add the permissions object and include the appropriate scopes for your skill. For details, see Skill Manifest.

  • Include an events object and the subscribed events in your skill manifest.

  • Configure your AWS Lambda function endpoint with an Alexa trigger.

Although many of the following events show an accessToken field, accessToken is not present if the customer hasn't 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.

To obtain a customer consent token for an out-of-session interaction with your skill, see Send messages to your skill.

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 deprecated in favor of eventCreationTime." Use eventPublishingTime to verify that the request was sent no later than 150 seconds after the original published time.

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 can't, at a later time, retrieve past events from Alexa.

Order of event arrival to the skill

The order in which the skill receives events is not necessarily the same as when the event 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 shouldn't act as if the skill is enabled.

Skill events

For the list of supported events, see Skill events.

Was this page helpful?

Last updated: Aug 07, 2024