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 to be notified 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 when the corresponding list event is received.

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. In order 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.

Permissions to access specified customer data are granted 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. 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. If the account has been linked, the access token is included in all subsequent events.

Similarly, the permissions object, which contains the consentToken field, if the customer has granted permissions to the skill, is added to the user object for both skill events and list events, but is otherwise not present. If the consentToken field is null, the permissions object is not present.

Delivery of Events to the Skill

Alexa will attempt to redeliver events if an acknowledgement is not sent by the skill service, for up to one hour. If the skill service receives an event, and the skill service sends an acknowledgment in response, this event must then be managed by the skill service. In either case, the skill service cannot, at a later time, retrieve past events from Alexa.

Order of Event Arrival to the Skill

List events and skill events are sent to the skill, but the order in which the skill receives these events is not necessarily the same as when they occurred.

Thus, any action that the skill takes as a result of an event should consider the timestamp of the event. For example, if a list item is added and then deleted, 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, the US endpoint https://api.amazonalexa.com should be called 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, which can be obtained from 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 a new item in a list has been created. 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 an item in a customer list has been updated. It is sent when an item status changes or an item value is updated.

{
  "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 an item in a customer list has been deleted.

{
  "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 a new customer list is created. 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 a customer list is updated. 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 a customer list is deleted. 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", ...]
    }
  }
}

Frequently Asked Questions

For an example that shows how to include code in your skill service to handle events, see Alexa List Events Project.

See also: Creating and Managing List Skills: An FAQ.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment