How to use the Customer Profile API in Amazon Alexa skills

Less than a month ago, Amazon released a brand new API called the Customer Profile API, which allows access to user’s name, email address, phone number, and home address. This can be especially useful if you wish to, for example, send the user an email or a text message through your skill, or as an alternative to account linking. See the official Amazon blog post here.

To get started, head in to the build page of your skill in the Alexa Skills Kit. Then head in to the permissions tab on the left side.

Permissions tab

In the permissions tab you will see a few options to enable with switches. For the purposes of this tutorial, we will only enable the Customer Email Address, but the process is the same for all selections.

Note: When at least one of these options is selected, the user must consent to revealing this information to your skill. This is fortunately handled by Amazon, in the form of a dialog prompt within the Alexa mobile companion app, once the user enables the skill.

Once that is completed, we can now make an intent to fetch the user’s email address. Here is what mine looks like:

And then we can create the handler for the intent in the index.js file that is run by AWS lambda (I use the node.js sdk v2):

Be sure to add this intent handler at the bottom of your index.js file, in the .addRequestHandlers function call.

In order to retrieve the user’s email address (or any of the other options), we must make an api call. I’ve set up a global constant at the top of my file that we will use in the next step:

const baseURL = "https://api.amazonalexa.com";

In order to make the API call, I use a library called axios. To use this library, you must install it via npm using

npm install axios

in the command line, in the same directory as your index.js file. Don’t forget to import it into your index.js as well.

const axios = require("axios");

In order to perform the API request, you must obtain the apiAccessToken specific to your skill. Inside of the GetMyEmailIntentHandler, I have

var apiaccessToken =
handlerInput.requestEnvelope.context.System.apiAccessToken;

Outside of the intent handler, I have created a function that returns the user’s email.

This function takes the apiAccessToken and a callback function as parameters. The return value is in JSON format, and the user’s email will be located in the response.data node of the JSON tree. The user’s email is passed to the callback function.

Back in the GetMyEmailIntentHandler, after collecting the apiAccessToken, I return a Promise which fetches the user’s email, then returns a speak instruction to Alexa in the anonymous callback function.

The speak instruction must be in a callback function of the getEmail function because the speech text relies on the return value of getEmail(). Otherwise, when this intent is invoked, getEmail() would be called but because it is an asynchronous method, it would not complete until after the speak instruction. Alexa would instead say “Your email is undefined.”

If you have any questions, comments, or concerns, please do let me know in the comments section. Thank you!

Full source code: