Home > Alexa > Alexa Skills Kit

List Events in Alexa Skills

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.

In order 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. In order to use 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 one or more list items have been created.

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "String"
      },
      "user": {
        "userId": "String",
        "accessToken": "String",
        "permissions": {
          "consentToken": "String"
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ItemsCreated",
    "requestId": "String",
    "timestamp": "2017-08-16T19:53:14Z",
    "body": {
      "listId": "String",
      "listItemIds": [
        "String"
      ]
    }
  },
  "session": {
    "attributes": {}
  }
}

List Items Updated Event

This event indicates that one or more list items have been updated.

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "String"
      },
      "user": {
        "userId": "String",
        "accessToken": "String",
        "permissions": {
          "consentToken": "String"
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ItemsUpdated",
    "requestId": "String",
    "timestamp": "2017-08-16T19:53:14Z",
    "body": {
      "listId": "String",
      "listItemIds": [
        "String"
      ]
    }
  },
  "session": {
    "attributes": {}
  }
}

List Items Deleted Event

This event indicates that one or more list items have been deleted.

{
  "version": "1.0",
  "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": "2017-08-16T19:53:14Z",
    "body": {
      "listId": "String",
      "listItemIds": [
        "String"
      ]
    }
  },
  "session": {
    "attributes": {}
  }
}

Frequently Asked Questions

Q. How can you view a list skill created using the Skill Management API (SMAPI) in the Amazon Developer Portal?

List skills must be created using SMAPI, and are viewable and editable only through SMAPI. You cannot view or edit list skills on the Amazon developer portal (https://developer.amazon.com/).

Q. When is an event generated by a customer action?

Any customer with a list skill enabled causes a list event to be generated whenever the customer adds, modifies, or deletes an item from their lists. A skill event is generated whenever a customer enables or disables the skill, links or unlinks a third-party account with the skill, grants permissions to a skill, or changes the permissions grant to the skill.

Q. Are IDs such as alexa_user_id, list_id, and list_item_id persistent after the customer generates a skill event?

The alexa_user_id value changes whenever a customer disables and then re-enables the skill. Account linking or unlinking does not change the alexa_user_id value. The list_id and list_item_id values are unchanged by when a skill is disabled and re-enabled.

Q. How should the developer handle localization of the To-Do and Shopping lists?

The default lists (To-Do and Shopping List) list_id values are base-64 encoded strings with these formats:

  • <Internal_identifier>-TASK for the to-do list
  • <Internal_identifier>-SHOPPING_LIST for the shopping list

Developers can base64 decode the list_id value and look for the specified string at the end. This string is constant and agnostic to localization.

Q. Can a customer grant just one of list read or list write permissions?

A customer may decide to grant one or both of list read and list write permissions.

Q. Are List APIs idempotent? Can a deleted item be deleted again?

Once an item is deleted, it is no longer in the system and subsequent calls to delete the item will result in the system throwing an “Object not found” exception. Similarly, multiple calls to create an item will create multiple items, even if each call is identical.

Q. What timeouts are enforced on the Event calls? In particular, on initial linking, a first “sync” might be quite large and slow.

The timeout period is 30 seconds for AWS Lambda skill services, by default. This value can be changed in the skill service settings. The timeout is 10 seconds for HTTPS endpoints.

Q. What is the server retry logic for list events and skill events?

The system retries with an exponentially increasing delay, starting at 30 seconds and doubling each time the endpoint fails to receive the message. The maximum period of time for which these retries occur is one hour. The maximum delay between retries is 30 minutes. For messages sent through the Skill Messaging API, the maximum retry time is set using the expiresAfterSeconds field, and can be set to be up to 24 hours (86400 seconds).

Q. Does the datetime format differ for List API calls and for list events?

List events use the ISO8061 datetime format. The List API returns datetimes in this format: “Sat Jul 22 10:41:04 UTC 2017”

Q. Can a customer change regions and thus require a different API endpoint for calling the List APIs?

Yes, a customer can change the region, but you can continue using the same endpoint for calling List APIs. The system will internally route the requests as per the customer’s preferred market place. When a customer changes the preferred market place, the data controlled by the skill will not be migrated automatically.

Q. Are list item moves represented as a delete list item and create list item event? Is the item_id maintained?

When a customer moves an item across lists using the Alexa app, two events are generated for the operation. These events are ItemsDeleted on the source list, and an ItemsCreated event on the destination list. The item_id value is maintained.

Q. Can a developer determine that an event has been triggered due to their skill?

Consider this scenario:

  • The customer creates a to-do in the app.
  • The skill service uses the Skill Messaging API to send a message to the skill to create a list item in Alexa.
  • The skill receives the Skill Messaging API message and POSTs to householdlist and list items.

In response to the POST, the skill service records the alexa_item_id locally. An ItemsCreate event also occurs as a list item was just created. Alexa triggers an event even if a list item is created by calling List API. Skill developers can use the item_id value returned by CreateListItem to uniquely identify an item.

Q. What are some sample calls to get an out-of-session consent token to call List APIs?

To obtain an out-of-session Skill Messaging API token:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
client_id=amzn1.application-oa2-client.e8621d747d6742d4a7aff2bbc614fc0d&client_secret=9ef36f40378fa1a7XXXXXXXXXXX12acd650030b07bb0fcc7e467&grant_type=client_credentials&scope=alexa%3Askill_messaging

Response:

{
    "access_token": "Atc|XXXXXXXXXXXXXXXXXUSyLA",
    "scope": "alexa:skill_messaging",
    "token_type": "bearer",
    "expires_in": 3600
}

To POST a message to the Skill Messaging API:

POST /v1/skillmessages/users/amzn1.ask.account.XXXXXXXXXXXXXX HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer Atc|XXXXXXXXXX
Content-Type: application/json
Cache-Control: no-cache
Postman-Token: 98b62082-ff25-a7de-f33b-95d9424beb22
{"data":{"notificationTitle":"NewMessagefromBackend","spokenOutput":"Hi,ThisisthemessagesentfromBackend."},"expiresAfterSeconds":60}
Response: 202 Accepted

Q. Is a client id unique to a skill?

The ClientId and ClientSecret are unique to a skill, means there is a one-to-one mapping between a ClientId value and a skill. Similarly, there is a one-to-one mapping between an actual customer and the alexa_user_id for a skill. If a customer has multiple Alexa skills enabled, the customer has a separate and unique alexa_user_id value for each of these skills.

For example, suppose a customer has two skills: ABCSkill and XYSSkill with ClientId_ABC and ClientId_XYS.

When the customer has enabled ABCSkill and XYSSkill, each has a separate alexa_user_id, such as AlexaUserId_ABC for ABCSkill and AlexaUserId_XYS for XYZSkill, and these are not the same.

If you call the Skill Messaging API with (ClientId_ABC and ClientSecret_ABC and AlexaUserId_ABC), you will get the correct response, and the same applies for ClientId_XYZ, ClientSecret_XYZ and AlexaUserId_XYZ.

Q. How should the skill service verify the authenticity of events received by skill endpoints?

Refer to Alexa Skills Kit Security Testing. Do not depend solely on the access token to validate the incoming request. All third-party skills must validate the request signature to ensure that the request was sent by Alexa. Otherwise the skill cannot pass certification to go live.