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 does not 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 do not 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.

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. 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 is not present.

Delivery of events to the skill

When the skill service doesn't send an acknowledgment to an event, Alexa will attempt 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 cannot, 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 is not 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 should not 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 does not 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 cannot 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 cannot 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.