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:

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.

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.

Last updated: Mar 14, 2023