List Events in Alexa Skills
Any Alexa skill with the appropriate customer-granted permissions can access a customer's Alexa lists. In addition, skill developers now have the capability to integrate with skill events and list events directly. The skill doesn't have to call the List API to see if the list has changed, but can subscribe to list events notifications when a list event occurs. Access to these events allows skill developers to build richer skill and external app experiences. For example, a third-party app can leverage access to Alexa lists, and the list change events, to synchronize its customer lists in the app with the customer's Alexa Lists on receipt of the corresponding list event.
To synchronize an Alexa list with a list stored on a third-party app, the customer must link an Alexa account with the third-party app account using Alexa account linking. To know when a customer starts and stops sharing the lists, an app must know when a customer grants and revokes list permissions to the skill. The use of list events and skill events allow the app to have this information.
Alexa grants permissions to access specified customer data at the skill level, and there are no event-specific permissions.
Use events in your skill service
If you want a custom skill with list management capabilities, follow the instructions in Access the Alexa Shopping and To-Do Lists. However, these list management features don't include list events. To use list events in your skill service, you must create a list skill. For details, see Steps to Create a List Skill.
Access tokens, permissions, and consent tokens in events
Although many of the following events show an accessToken
field, note that accessToken
isn't present if the customer hasn't linked their Alexa account to the appropriate third-party app. After the customer links their account, all subsequent events include the access token.
Similarly, after the customer grants permissions to the skill, the user
object includes the permissions
object which contains the consentToken
field for both skill events and list events. If the consentToken
field is null, the permissions
object isn't present.
Delivery of events to the skill
When the skill service doesn't send an acknowledgment to an event, Alexa attempts to redeliver events for up to one hour. When the skill service does send an acknowledgment on receipt of an event, the skill service must manage this event. 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 list events and skill events isn't necessarily the same order as when they occurred.
Thus, consider the timestamp of the event when taking action on the event. For example, if a customers adds and then deletes a list item, resulting in a list item added event and a list item deleted event, and the list item deleted event arrives to the skill before the list item added event, the skill shouldn't add the item to the Alexa lists.
apiEndpoint value used in event
For customers in the EU region, the value of apiEndPoint
received in the events is https://api.eu.amazonalexa.com
. For calling the List API, use the US endpoint https://api.amazonalexa.com
for all customers, regardless of their region, as the List API doesn't have an EU endpoint. However, for calling the Skill Messaging API, you should call the appropriate endpoint based on the customer region, found in the SkillEnabled
or SkillAccountLinked
event.
List events in JSON format
For general skill events, see Skill Events for Alexa.
timestamp
field, the format is UTC: YYYY-MM-DD'T'hh:mm:ss'Z'
. For all events that include a requestId
field, the format is alexa.list.event.UUID
.List items created event
This event indicates that the customer created a new item in a list. The skill should retrieve the item information by calling the GetListItem
API.
{
"version": "1.0", // Version, String
"context": {
"System": {
"application": {
"applicationId": "<skill_id>" // Skill id, String
},
"user": {
"userId": "amzn1.ask.account.VEBA...", // Skill user id, String
"accessToken": "<access_token>", // Token to identify user in 3P
"permissions": {
"consentToken": "Atza|IgEB..." // Token to call Lists API
}
},
"apiEndpoint": "https://api.amazonalexa.com" // Endpoint to call Lists API
}
},
"request": {
"type": "AlexaHouseholdListEvent.ItemsCreated",
"requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9", // String
"timestamp": "2017-09-15T01:46:14Z", // Timestamp, YYYY-MM-DD'T'hh:mm:ss'Z'
"body": {
"listId": "09d9d7df-05be-438c-veba-9d32968b4509", // List id, String
"listItemIds": [
"520a9f98-8e73-4fb8-veba-bfb6576cf623" // Item ids, String
]
}
},
"session": {
"attributes": {}
}
}
List items updated event
This event indicates that the customer has updated an item in a customer list or an item status changes.
{
"version": "1.0", // Version, String
"context": {
"System": {
"application": {
"applicationId": "<skill_id>" // Skill id, String
},
"user": {
"userId": "amzn1.ask.account.VEBA...", // Skill user id, String
"accessToken": "<access_token>", // Token to identify user in 3P
"permissions": {
"consentToken": "Atza|IgEB..." // Token to call Lists API
}
},
"apiEndpoint": "https://api.amazonalexa.com" // Endpoint to call Lists API
}
},
"request": {
"type": "AlexaHouseholdListEvent.ListUpdated",
"requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9", // String
"timestamp": "2017-09-15T01:46:14Z", // Timestamp, YYYY-MM-DD'T'hh:mm:ss'Z'
"body": {
"listId": "09d9d7df-05be-438c-veba-9d32968b4509", // List id, String
"listItemIds": [
"520a9f98-8e73-4fb8-veba-bfb6576cf623" // Item ids, String
]
}
},
"session": {
"attributes": {}
}
}
List items deleted event
This event indicates that the customer deleted an item in a customer list.
{
"version": "1.0", // Version, String
"context": {
"System": {
"application": {
"applicationId": "<skill_id>" // Skill id, String
},
"user": {
"userId": "amzn1.ask.account.VEBA...", // Skill user id, String
"accessToken": "<access_token>", // Token to identify user in 3P
"permissions": {
"consentToken": "Atza|IgEB..." // Token to call Lists API
}
},
"apiEndpoint": "https://api.amazonalexa.com" // Endpoint to call Lists API
}
},
"request": {
"type": "AlexaHouseholdListEvent.ListDeleted",
"requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9", // String
"timestamp": "2017-09-15T01:46:14Z", // Timestamp, YYYY-MM-DD'T'hh:mm:ss'Z'
"body": {
"listId": "09d9d7df-05be-438c-veba-9d32968b4509", // List id, String
"listItemIds": [
"520a9f98-8e73-4fb8-veba-bfb6576cf623" // Item ids, String
]
}
},
"session": {
"attributes": {}
}
}
List created event
This event indicates that the customer creates a new customer list. The skill should retrieve information about this list by calling the GetListsMetadata
API.
{
"version": "1.0", // Version, String
"context": {
"System": {
"application": {
"applicationId": "<skill_id>" // Skill id, String
},
"user": {
"userId": "amzn1.ask.account.VEBA...", // Skill user id, String
"accessToken": "<access_token>", // Token to identify user in 3P
"permissions": {
"consentToken": "Atza|IgEB..." // Token to call Lists API
}
},
"apiEndpoint": "https://api.amazonalexa.com" // Endpoint to call Lists API
}
},
"request": {
"type": "AlexaHouseholdListEvent.ListCreated",
"requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9", // String
"timestamp": "2017-09-15T01:46:14Z", // Timestamp, YYYY-MM-DD'T'hh:mm:ss'Z'
"body": {
"listId": "09d9d7df-05be-438c-veba-9d32968b4509" // List id, String
}
},
"session": {
"attributes": {}
}
}
List updated event
This event indicates that the customer updates a customer list. Initially, this event indicates that a customer has renamed the list. A customer can't rename Alexa To-Do Lists or Alexa Shopping Lists.
{
"version": "string",
"context": {
"System": {
"application": {
"applicationId": "string"
},
"user": {
"userId": "string",
"accessToken": "string",
"permissions": {
"consentToken": "string"
}
},
"apiEndpoint": "https://api.amazonalexa.com"
}
},
"request": {
"type": "AlexaHouseholdListEvent.ListUpdated",
"requestId": "string",
"timestamp": "string",
"body": {
"listId" : "string"
}
}
}
List deleted event
This event indicates that the customer deletes a customer list. A customer can't delete Alexa To-Do or Alexa Shopping Lists.
{
"version": "string",
"context": {
"System": {
"application": {
"applicationId": "string"
},
"user": {
"userId": "string",
"accessToken": "string",
"permissions": {
"consentToken": "string"
}
},
"apiEndpoint": "https://api.amazonalexa.com"
}
},
"request": {
"type": "AlexaHouseholdListEvent.ItemsDeleted",
"requestId": "string",
"timestamp": "string",
"body": {
"listId" : "string",
"listItemIds" : ["string", ...]
}
}
}
Sample code
For an example that shows how to include code in your skill service to handle events, see Alexa List Events Demo.