List Management FAQ

The following frequently asked questions (FAQ) answer common questions about list management.

Permissions

Q: Can a customer grant access to a single Alexa list?

No, a customer can't limit the lists that they share with a skill. However, a skill might choose to interact only with those lists that are of interest.

Q: Can Alexa customers share their lists with other customers within Amazon?

Yes, if the other customers are within the same Amazon household. For a details about Amazon households, see Household Profiles on Alexa Devices.

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

A customer can grant one or both of the list read and list write permissions.

Q: Can an Alexa customer grant access to the Alexa Shopping and To-Do lists to more than one skill?

Yes.

List management

Q. Are IDs such as userId, listId, and listItemId persistent after the customer generates a skill event?

The userId value can change when a customer disables, and then re-enables the skill. Account linking or unlinking doesn't change the userId value. The listId and listItemId values are persistent and don't change when a skill is disabled and re-enabled.

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

On the default lists, such as the Alexa Shopping and To-Do lists, listId values are base-64 encoded strings with these formats:

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

You can base64 decode the listId value and look for the specific string at the end. This string is constant and agnostic to localization.

Q: Do the list management capabilities support custom list metadata?

You can access custom list metadata with the Get lists metadata REST API.

Q: Can a customer delete their Alexa list?

A customer can't delete a default Alexa list, although a customer can delete all the items on the default Alexa Shopping and To-Do lists. A customer can delete a custom list, if all the items on the list are deleted first.

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

After an item is deleted, that item is no longer in the system and subsequent calls to delete the item result in an "Object not found" exception. Similarly, multiple calls to create an item creates multiple items, even if each call is identical.

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

Yes, a customer can change regions, but you can continue to use the same endpoint for List Management REST APIs. The system internally routes the requests per the customer's preferred marketplace. When a customer changes their preferred marketplace, the data controlled by the skill isn't migrated automatically.

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

The List Management REST API returns ISO8061 datetime format. List events use datetimes in UTC format: Sat Jul 22 10:41:04 UTC 2017.

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

For details about the message format and code examples to obtain an out-of-session access token to access List Management APIs directly, see Get a User-Specific Access Token for Out-of-Session Calls to Alexa.

Q: Can a skill use both account linking and list management capabilities?

Yes. This feature allows you to reference customer Alexa lists in your external apps. To set up account linking, see Understand Account Linking.

List skills

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

List skills must be created using SMAPI, and are viewable and editable only through SMAPI. You can't view or edit list skills on the Alexa developer console.

Events

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

A list event is generated when the customer adds, modifies, or deletes an item from their lists. A skill event is generated when the 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 list item moves represented as a delete list item and create list item event? Is the listItemId 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 listItemId value is maintained.

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's 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. 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 app 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 the householdlist resource and list items.

In response to the POST, the skill service records the listItemId 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 the List Management REST API. Skill developers can use the listItemId value returned by CreateListItem to uniquely identify an item.

Q. What are some sample calls to get an out-of-session access token to call Skill Messaging APIs?

For details about the message format and code examples to obtain an out-of-session access token, see Request Format to Obtain Access Token.

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 userId for a skill. If a customer has multiple Alexa skills enabled, the customer has a separate and unique userId 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 userId, such as AlexaUserId_ABC for ABCSkill and AlexaUserId_XYS for XYZSkill.

If you call the Skill Messaging API with ClientId_ABC and ClientSecret_ABC and AlexaUserId_AB, you 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?

Don't depend solely on the access token to validate the incoming request. All third-party skills must validate the request signature to make sure that the request was sent by Alexa. Otherwise the skill can't pass certification to go live. For details, see Alexa Skills Kit Security Testing.