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 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. For example, a your app or website 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 your app or website, the customer must link an Alexa account with the app account by 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. List events and skill events allow the app to have this information.
Alexa grants permissions to access specified customer data at the skill level. There are no event-specific permissions.
Prerequisites
To use list events in your skill service, your skill must meet the following requirements:
- You must create a list skill. For more details, see Steps to Create a List Skill.
- You must enable account linking in your skill. For details about account linking, see Understand Account Linking.
Access tokens, permissions, and consent tokens in events
An event contains an accessToken
property. However, if the customer hasn't linked their Alexa account to the your app or website yet, accessToken
isn't present in the event. 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
property for both skill events and list events. If the consentToken
property is null, the permissions
object isn't included in the message.
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 the event occurred.
Consider the timestamp of the event when taking action on the event. For example, if a customers adds and then deletes a list item, Alexa sends a list item added event and a list item deleted event. If 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.
API endpoint for list events
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 the 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.
Related topics
- Steps to Create a List Skill
- Creating and Managing List Skills FAQ
- Access the Alexa Shopping and To-Do Lists
Last updated: Mar 14, 2023