Access the Alexa Shopping and To-Do Lists

Alexa customers have access to two default lists: Alexa shopping list and Alexa to-do list. Customers can review and modify their Alexa lists with voice or the Alexa app. For example, a customer can ask Alexa to add items to the Alexa Shopping List at home, and then, at the store, view and update the items in the Alexa app.

You can access the Alexa shopping and to-do lists in your custom skill. And, you can create and manage custom lists. For details about list management see, List Skills.

Add list management capabilities

To access Alexa , you need a custom skill. For details about how to create a custom skill, see Steps to Build a Custom Skill.

Complete the following steps to add list management capabilities to your skill:

  1. Configure permissions to access the Alexa lists in your skill.
  2. Design a user intent model that uses customer Alexa lists.
  3. Handling customer missing permissions.
  4. Get access the customer's Alexa lists.
  5. Implement the list management capabilities in your skill service code.

Configure permissions

Use the Alexa developer console to set the appropriate permissions to access the customer's Alexa lists. To support the features of your skill, request Lists Read or Lists Write permissions, or both.

Set up permission for list access in the developer console

  1. Sign in to the Alexa developer console.
  2. From the skill list, locate your custom skill, and then, in the dropdown under ACTIONS, select Edit.
  3. In the left pane, click TOOLS, and then click Permissions.
  4. To enable read permission, toggle Lists Read.
  5. To enable writer permission, toggle Lists Write.

Handle missing permissions grants

To access the customer's Alexa lists, the customer must grants permissions to a skill in the Skills section of the Alexa app. Your skill has access until the customer revokes permissions. At any time, the customer can change the allowed access for that skill in Manage Settings on the skill's page in the Alexa app.

If the customer hasn't granted your skill access to their Alexa lists, you must handle this case gracefully. As a best practice, provide a voice prompt and display a permissions card in the Alexa app that explains to the customer to grant the required access in the Alexa app.

The following example code shows a card format for write permissions to a customer's Alexa lists.

{
  "version": "1.0",
  "response": {
    "card": {
      "type": "AskForPermissionsConsent",
      "permissions": [
        "alexa::household:lists:read",
        "alexa::household:lists:write"
      ]
    }
  }
}

The list permissions are alexa::household:lists:read and alexa::household:lists:write for read and write respectively.

Get access to Alexa lists

To access list management capabilities, your skill requires an access token that indicates that the customer has granted the skill permission to access the customer's Alexa lists. Obtain this token with an in-session request. For example, a customer voice request or an out-of-session request.

In-session intent request

Each request sent to your skill includes an API access token (apiAccessToken) that encapsulates the permissions granted to your skill. You need to retrieve this token value and use it in the requests related to list management.

The following example shows a full request. The apiAccessToken is nested in the System object, which is nested in the context object. For more details about the parameters of such a request, see: Request Body Syntax.

{
  "version": "1.0",
  "session": {
    "new": true,
    "sessionId": "amzn1.echo-api.session.[unique-value-here]",
    "application": {
      "applicationId": "amzn1.ask.skill.[unique-value-here]"
    },
    "attributes": {
      "key": "string value"
    },
    "user": {
      "userId": "amzn1.ask.account.[unique-value-here]",
      "accessToken": "Atza|AAAAAAAA...",
      "permissions": {
        "consentToken": "ZZZZZZZ..."
      }
    }
  },
  "context": {
    "System": {
      "device": {
        "deviceId": "string",
        "supportedInterfaces": {
          "AudioPlayer": {}
        },
        "persistentEndpointId" : "amzn1.alexa.endpoint.[unique-value-here]"    
      },
      "application": {
        "applicationId": "amzn1.ask.skill.[unique-value-here]"
      },
      "user": {
        "userId": "amzn1.ask.account.[unique-value-here]",
        "accessToken": "Atza|AAAAAAAA...",
        "permissions": {
          "consentToken": "ZZZZZZZ..."
        }
      },
      "person": {
        "personId": "amzn1.ask.person.[unique-value-here]",
        "accessToken": "Atza|BBBBBBB..."
      },
      "unit": {
        "unitId": "amzn1.ask.unit.[unique-value-here]",
        "persistentUnitId" : "amzn1.alexa.unit.did.[unique-value-here]"
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "AxThk..."
    },
    "AudioPlayer": {
      "playerActivity": "PLAYING",
      "token": "audioplayer-token",
      "offsetInMilliseconds": 0
    }
  },
  "request": {}
}

Thus:

accessToken = this.event.context.System.apiAccessToken

For details, see Handling Requests Sent by Alexa.

Out-of-session interaction

Your app can request an out-of-session access token when it needs to access the customer Alexa lists outside of the customer's voice request, following these steps:

  1. Obtain the Skill Messaging API access token, using the ClientId and ClientSecret as inputs. To get these ClientId and ClientSecret values, refer to the Permissions page for your skill in the developer console. For details about the request format, see Configure an Application or Service to Send Messages to Your Skill. If your skill has been managed through SMAPI, you can still see these values in the developer console. Go to the list of skills. Those skills that have the appropriate permissions display the link View Skill ID and Client Secret. When you click this link, the Skill ID, Client ID, and Client Secret appear in a popup.

  2. Once the access token is obtained, the app makes an asynchronous call to the Skill Messaging API using the Skill Messaging API access token and the userId value, which was obtained during an earlier customer voice interaction. The Skill Messaging API calls the skill back with the customer consent token.

Out-of-session token workflow
Out-of-session token workflow

Skill Messaging API Access Token

The third-party application requires authorization to send messages to the skill. This authorization is obtained with the following API via an HTTPS request, as described.

Request Format

This section documents the format for the request.

HTTP Header

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
 
Parameter Description Example
Content-Type The content type of the resource. Must be application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded

Request Body Syntax

grant_type=client_credentials&client_id=(clientID)&client_secret=(clientSecret)&scope=alexa:skill_messaging

Request Body Parameters

 
Parameter Description Example
grant_type Value must be client_credentials grant_type=client_credentials
client_id The ClientId value client_id=amzn1.iba-client...
client_secret The ClientSecret value client_secret=...
scope Value must be alexa:skill_messaging scope=alexa:skill_messaging

Sample cURL Request

curl -k -X POST -H
 'Content-Type: application/x-www-form-urlencoded' -d
'grant_type=client_credentials&client_id=xxxx&client_secret=yyyy&scope=alexa:skill_messaging'
 https://api.amazon.com/auth/o2/token

Response Format

If your request is not successful, you will receive a non-200 error status code. In the case of a non-200 code, the response message may contain the following parameter in the body of the JSONObject:

reason: <<The reason the request was not accepted>>

A successful response format is as follows.

HTTP Header

X-Amzn-RequestId: d917ceac-2245-11e2-a270-0bc161cb589d
 Content-Type: application/json

Response Body Syntax

{
  "access_token": "Atc|MQEWYJxEnP3I1ND03ZzbY_NxQkA7Kn7Aioev_OfMRcyVQ4NxGzJMEaKJ8f0lSOiV-yW270o6fnkI",
  "expires_in": 3600,
  "scope": "alexa:skill_messaging",
  "token_type": "Bearer"
}

Request Body Parameters

 
Parameter Description Example
access_token An access token that must be used for all requests "access_token":"Atc|MQEWYJxEnP3I1ND03Zz..."
expires_in The duration in seconds of the access token lifetime. For example, 3600 denotes that the access token expires in one hour from the time the response was generated. "expires_in":3600
scope Value will be alexa:skill_messaging "scope":"alexa:skill_messaging"
token_type Only Bearer tokens are supported "token_type":"Bearer"

Errors

Status CodeTypeDescription
400INVALID_REQUESTReasons for this response include:
- The content type is not supported by the authorization server. In other words, it is not application/x-www-form-urlencoded.
- The request is missing a required parameter: grant-type, scope, client_id, client_secret.
- The request is otherwise malformed.
400 UNAUTHORIZED_CLIENT The client is not authorized for the requested operation.
400 UNSUPPORTED_GRANT_TYPE The grant type is not supported by the authorization server. In other words, it is not client_credentials.
400 INVALID_SCOPE The requested scope is invalid, which means it is not alexa:skill_messaging.
401 INVALID_CLIENT The client authentication failed.
500 SERVER_ERROR There was an internal server error. The requester may retry the request.
503 SERVICE_UNAVAILABLE The server is temporarily unavailable. The requester must retry later honoring the Retry-After header included in the response. See the HTTP/1.1 specification, section 14.37, for possible formats for the Retry-After value.

List management capabilities

Use the List Management REST APIs provide create, read, update, delete, and traverse customer Alexa lists. Archived lists are read-only lists. You can read, but not update or delete, items from an archived list.

In addition to the list management REST APIs, your skill can access list events and skill events. Use these events to enhance the skill's functionality.

To use SMAPI in a skill, you must manage the skill through the Alexa Skills Kit Command Line Interface (ASK CLI). After you manage your skill through ASK CLI, you can't return its management to the developer console.

Throttling restrictions

List API requests are throttled at 25 TPS per skill. Any requests beyond that limit receive HTTP 400 error code, with the message "Rate exceeded". The request can then be retried.

Sample code

For sample code about how to incorporate lists in your skill, see Alexa List Access Demo.