Add Events to Your Skill

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

When you develop a skill with Alexa Skills Kit (ASK) Command Line Interface (CLI), you can modify the skill schema to include event subscriptions that allow you to receive event notifications when the subscribed event occurs for a customer. The pre-built and custom voice interaction models support skill events. For more details about events, see Skill Events.

To add events to an existing skill, follow these instructions.

A custom skill manifest can include skill events if updated in this manner.

Prerequisites

Before you can update your skill definition, install ASK CLI. For details, see Quick Start Alexa Skills Kit Command Line Interface for installation instructions.

Update your skill definition to include events

Complete the following steps to update your skill definition to include events. For details about the properties in the skill manifest schema, see Skill Manifest. For an example schema, see Custom skill manifest

Download your existing skill manifest by using the get-skill-manifest command.

ask smapi get-skill-manifest -s {skillId} -g {development|certified|live} > skill.json
Update the skill.json file to include the events object with the list of events in events.subscriptions.
If necessary for your skill, add the permissions object and include the appropriate scopes for your skill.
Update your skill definition by using the update-skill-manifest command.

ask smapi update-skill-manifest -s {skillId} -g {development|certified|live} --manifest "$(cat skill.json)"

Note: You can't change the configuration of a live skill. Any changes to the skill configuration require recertification, so a new development version is automatically created in the developer console. This version has the same information as the original live version. For details, see Revise and update your skill after certification or publication.

Supported skill events

The following sections list the JSON format for each skill event. If the customer hasn't granted permission, the permissions object isn't present. 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 apps and services that support out-of-session (non-voice) user interactions. Because this event is triggered by account linking, this event notifies your app 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).

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"
    }
}

ReminderStarted

Alexa generates the ReminderStarted when a reminder starts ringing. The skill service can then take corresponding actions at the trigger time.

{
  "version": "1.0",                                 
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"             
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",      
        "accessToken": "<access_token>",          
        "permissions": {
          "consentToken": "Atza|IgEB..."            
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"  
    }
  },
  "request": {
    "type": "Reminders.ReminderStarted",
    "requestId": "913e4588-62f9-4d5b",              
    "timestamp": "2017-09-15T01:46:14Z",            
    "body": {
      "alertToken": "<alert-token-value>",      
    }
  },
  "session": {
    "attributes": {}
  }
}

ReminderCreated

Alexa generates the ReminderCreated event after creating a reminder. Alexa sends this event to the skill that created the reminder, not the user who used the skill.

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",
        "accessToken": "<access_token>",
        "permissions": {
          "consentToken": "Atza|IgEB..."
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "Reminders.ReminderCreated",
    "requestId": "<requestId-value>",
    "timestamp": "2017-09-15T01:46:14Z",
    "body": {
      "alertToken": "<alert-token-value>"
    }
  },
  "session": {
    "attributes": {}
  }
}

ReminderDeleted

Alexa generates the ReminderDeleted event after the user deletes a reminder. Alexa sends this event to the skill that created the reminder.

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",
        "accessToken": "<access_token>",
        "permissions": {
          "consentToken": "Atza|IgEB..."
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "Reminders.ReminderDeleted",
    "requestId": "<requestId-value",
    "timestamp": "2017-09-15T01:46:14Z",
    "body": {
      "alertTokens": "[alert-token-values]"
    }
  },
  "session": {
    "attributes": {}
  }
}

ReminderUpdated

Alexa generates the ReminderUpdated event when a reminder updates. This event doesn't provide any details on the update, except for the current state of the reminder. To get further update details, the skill should use the List reminders.

Possible updates include one of the following:

Completed
Turned on

Or, when a reminder:

Has its trigger time updated.
Has its label updated.

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",
        "accessToken": "<access_token>",
        "permissions": {
          "consentToken": "Atza|IgEB..."
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "Reminders.ReminderUpdated",
    "requestId": "913e4588-62f9-4d5b",
    "timestamp": "2017-09-15T01:46:14Z",
    "body": {
      "status": "DEFERRED",
      "alertToken": "09d9d7df-05be-438c-veba"
    }
  },
  "session": {
    "attributes": {}
  }
}

ReminderStatusChanged

Alexa generates the ReminderStatusChanged event when the reminder status changes.

Possible statuses include one of the following:

On
Completed
Deferred

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",
        "accessToken": "<access_token>",
        "permissions": {
          "consentToken": "Atza|IgEB..."
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "Reminders.ReminderStatusChanged",
    "requestId": "913e4588-62f9-4d5b",
    "timestamp": "2017-09-15T01:46:14Z",
    "body": {
      "status": "COMPLETED",
      "alertToken": "09d9d7df-05be-438c-veba"
    }
  },
  "session": {
    "attributes": {}
  }
}

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