Request Recognized Speaker Contact Information for Use in Your Skill

If your skill implements personalization for recognized speakers, and the Alexa user is a recognized speaker with a voice profile and Personalize skills enabled in the Alexa app, your skill can request the user's permission to access the contact information associated with the user's voice profile. The contact information includes the name — either the full name or given name (first name) — and mobile number.

After receiving consent from the user, your skill can use the contact information to enable helpful experiences like the following:

  • Personalize responses to the user, such as "Welcome back, <first name>!"
  • Make a booking or appointment with your service on behalf of the user
  • Send detailed or follow-up information to the user by text

You access this contact information by using the Person Profile API.

Note

For sample code, see the Person Profile Demo in GitHub.

For details about personalization, see Add Personalization to Your Skill.

What is the difference between the Person Profile API and the Customer Profile API?

Each Alexa device is registered to only one Amazon account, but the device might have two or more speakers who interact with it. By default, a skill doesn't differentiate individual speakers, and therefore a skill can only personalize responses at the account level.

If your skill supports personalization, it can differentiate between recognized speakers. For a user to be a recognized speaker, they must have a voice profile and have Personalize skills enabled in the Alexa app. For details about how an Alexa user can enable or disable personalization, see Manage skill personalization as a user.

The Alexa Skills Kit has two APIs that relate to accessing contact information for Alexa users: the Person Profile API and the Customer Profile API. The difference between the two APIs is the following:

  • The Person Profile API returns the contact information of the person (that is, the recognized speaker) who is speaking to the Alexa device. For details, keep reading this page.
  • The Customer Profile API returns the contact information that is associated with the Amazon account to which the Alexa device is registered. Another difference between the Customer Profile API and the Person Profile API is that the Customer Profile API includes an email address with the returned contact information, whereas the Person Profile API does not. For details about the Customer Profile API, see Request Customer Contact Information for Use in Your Skill.

In other words, the "person" is the recognized speaker who is speaking to Alexa, and the "customer" is the Amazon account to which the Alexa device is registered. As such, the Person Profile API provides the most personalization.

Before you begin

To protect user data, any skill that uses recognized speaker contact information must meet the requirements listed next. If Amazon determines that your skill violates any of these requirements, Amazon will reject or suspend your submission and notify you using the email address associated with your developer account.

  • You must include a link to the Privacy Policy that applies to your skill on the Distribution page of the developer console.
  • Your skill must not be a child-directed skill. For details about child-directed skills, see Child-Directed Alexa Skills.
  • You must request permission to receive recognized speaker contact information only when required to support the features and services provided by your skill. You must use any personal information you request only as permitted by the user and in accordance with your privacy notice and applicable law.
  • You must not use personal information (full name, first name, or phone number) to link the user's account in the background. That is, you must not associate an Alexa user to a user in your account pool with the same contact information.
  • The skill must call the Person Profile API to get the latest user information every time the user invokes the skill with a request that needs this information.

Steps to create a skill that uses recognized speaker contact information

The overall flow to set up and implement a skill that uses recognized speaker contact information is as follows:

  1. You configure your skill in the developer console to indicate that it supports personalization and recognized speaker contact information. For details, see Configure your skill.
  2. When the user enables your skill, the Alexa app prompts the user to consent to provide their contact information. If the user chooses not to grant these permissions when enabling your skill, your skill can request this consent by using a permissions card when the user interacts with your skill and reaches a point at which the skill needs the information. Ensure that your skill handles the situation gracefully if the user refuses to grant permission to access this information.
  3. When the user launches the skill, you get the apiAccessToken from the LaunchRequest. For details, see Get the API access token from the launch request.
  4. You use the apiAccessToken as the authentication token when you make a request to the Person Profile API endpoint. For details, see Use the API access token in requests to the Person Profile API. For the API reference, see Person Profile API reference. If the user did not consent to provide permission to their contact data when they enabled the skill, you can ask them for permission again by using a permissions card.
  5. You test your calls to the Person Profile API as you develop your skill. For details, see Test your calls to the Person Profile API.

Step 1: Configure your skill

Before your skill can use the Person Profile API, you must configure the skill to support personalization and recognized speaker contact information.

Step 2: Prompt the user

Because of the way you configured your skill in the previous step, when the user enables your skill, the Alexa app prompts the user to consent to access their contact information.

If the user chooses not to grant these permissions when enabling your skill, your skill can request this consent by using a permissions card when the user interacts with your skill and reaches a point at which the skill needs the information. For details, see Step 3.

Step 3: Get the API access token from the launch request

Each request that Alexa sends your skill includes an API access token (apiAccessToken) that encapsulates the permissions granted to your skill. You must retrieve the token so that you can include it in requests for the user's contact information. Don't store the apiAccessToken, because it expires. Instead, get a fresh token from each subsequent request.

Step 4: Use the API access token in requests to the Person Profile API

To get the recognized speaker contact information, use the apiAccessToken as the authentication token when you make a request to the Person Profile API. For the API reference, see Person Profile API reference.

Step 5: Test your calls to the Person Profile API

Before you test your skill, read Test and Troubleshoot Personalization. Also make sure that you have a voice profile. For details, see Manage skill personalization as a skill user.

By using the Alexa Simulator in the developer console, you can call the Person Profile API and receive a non-error response that contains your own information. You can also test the flow in the case where the user hasn't granted permissions.

Best practices for when recognized speaker contact information is unavailable

As discussed previously, when the user enables your skill, the Alexa app prompts the user to consent to access their recognized speaker contact information. If the user chooses not to grant these permissions when enabling your skill, your skill can request this consent, when needed, by using a permissions card when the user uses the skill.

Keep in mind the following best practices for when recognized speaker contact information isn't available:

  • If possible, develop your skill so that some functionality is available without the requested permissions.
  • Prompt the user for permissions only when needed to fulfill a user request.
  • If the user doesn't consent to share the information and your skill can't continue without it, provide a graceful fallback message that indicates the skill can't function without this information, and end the session. Alternatively, you can provide a message that indicates that the skill will continue to work, but with reduced functionality compared to having the requested information.
  • Be prepared for the situation in which the user grants consent, but the required information is still unavailable. For example, the user hasn't provided their mobile number to Amazon. If the requested user information is unavailable, the API returns a 204 (no content) response. In this situation, if your skill cannot fulfill the request without some piece of information, you may prompt the user to enter this information in the Alexa app. For example: "Your <resource name> is not set. You can enter these details in the Alexa app under Settings > Your Profile, and then launch this skill again."
  • For a good user experience, ensure that you consider the skill workflow for all the scenarios in which you fail to get the desired information.

Person Profile API reference

The Person Profile API is a REST API that you use to access recognized speaker contact information. The requests succeed only if the user has granted the corresponding permission to your skill.

The endpoint for the Person Profile API varies depending on the geographic location of your skill. As shown in the following JSON example, you get the correct base URL from the apiEndpoint value in the System object.

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.<skill-id>"
      },
      "user": {},
      "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {}
}

HTTP method and URI path

Use the following paths to get the recognized speaker contact information. These are literal, case-sensitive strings.

Requested InformationPath
Full nameGET /v2/persons/~current/profile/name
Given nameGET /v2/persons/~current/profile/givenName
Mobile phone numberGET /v2/persons/~current/profile/mobileNumber

Request

Request header

Header Description Type Required

Authorization

A current access token in the format: Bearer {your access token}

String

Yes

Request example

Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer MQEWY...6fnLok
GET https://api.amazonalexa.com/v2/persons/~current/profile/name

Response

Response headers

Header Description
Content-Type The value will be application/json.
X-Amzn-RequestId Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

Response example

Header

Host: api.amazonalexa.com
X-Amzn-RequestId: xxxx-xxx-xxx
Content-Type: application/json

Body

{
   "countryCode" : "+1",
   "phoneNumber" : "999-999-9999"
}

Return types

The following is a list of return types, which are in JSON.

Information Type
Full namestring
Given namestring
Mobile phone number{ "countryCode": "string", "phoneNumber": "string" }

The phone number is a combination of countryCode and phoneNumber. The phoneNumber might also contain the countryCode, and is not guaranteed to be just the local part of the phone number. By itself, the phoneNumber value should be a valid number for dialing.

As such, the phone number may be in one of a variety of different formats. Some examples include: +917799827710, 7799827710, +91 7799 82 77 11, +91 7799-82-77-11. For just the country code, some possible formats include: +1, 001, 1.

Possible responses

Response Description
200 OK Successfully retrieved the requested information.
204 No Content The query did not return any results.
401 Unauthorized The authentication token is malformed or invalid.
403 Unauthorized

The authentication token doesn't have access to the resource. A possible cause is that the user didn't go through the following required steps:

  1. Create a voice profile.
  2. Enable Personalize skills in the Alexa app.
  3. Go to the skill detail page and grant permissions for the right speaker (voice profile).
  4. Invoke the skill to receive the apiAccessToken.
429 Too Many Requests The skill has been throttled due to an excessive number of requests.
500 Internal Error An unexpected error occurred.