Your Alexa Dashboards Settings

Skill Events in Alexa Skills

Skill developers now have the capability to integrate with Alexa skill events directly. If the skill is subscribed to these events, the skill is notified when an event occurs. Access to these events allows skill developers to build richer skill and external app experiences. A skill event is generated whenever 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 grant to the skill.

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

See also: List Events

Use Events in Your Skill Service

In order 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 permissionsInfo object if you include list events in your skill manifest, as described in Update Skill Definition.

  • 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.

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:

  1. 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.

  2. 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 timestamp 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

This event indicates that a customer has linked an account in a third-party application with the Alexa app. This event is useful for an application that support out-of-session (non-voice) user interactions so that this application can be notified when the internal customer can be associated with the Alexa customer. 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 the skill 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": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string",
        "accessToken": "string",
        "permissions": {
          "consentToken": "string"
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaSkillEvent.SkillAccountLinked",
    "requestId": "string" (alexa.skill.event.UUID),
    "body": {
      "accessToken": "string"
    },
    "timestamp": "string" (UTC: yyyy-mm-dd't'hh:mm:ss'z')
  }
}

Skill Enabled Event

This event is sent when a customer enables the skill.

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string"
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaSkillEvent.SkillEnabled",
    "requestId": "string",
    "timestamp": "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 user_id and no access token, because the access token is removed from Amazon systems whenever a customer disables the skill.

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string"
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaSkillEvent.SkillDisabled",
    "requestId": "string",
    "timestamp": "string"
  }
}

Skill Permission Accepted Event

This event is sent when a customer 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.

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

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

Skill Permission Changed Event

This event is sent if a customer 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.

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

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string",
        "accessToken": "string",
        "permissions":{ 
          "consentToken":"string"
        },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaSkillEvent.SkillPermissionChanged",
    "requestId": "string",
    "timestamp": "string",
    "body": {
      "acceptedPermissions":  [{
          “scope”: "string"
      }]
    }
  }
}