Request Recognized Speaker Contact Information for Use in Your Skill

Note: Sign in to the developer console to build or publish your skill.

If your skill implements personalization for recognized speakers, and the Alexa user is a recognized speaker with a voice ID and Personalize skills enabled in the Alexa app, your skill can request the user's permission to access the contact information associated with their voice ID. 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

For details about personalization, see Add Personalization to Your Skill. If you want to enable the user to verbally consent to share their contact information with your skill, see Use Voice-Forward Consent in Your Alexa Skill.

What's the difference between person profile and customer profile

Each Alexa device is registered to 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 ID 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.

To access contact information for Alexa users you can use the Person Profile or the Customer Profile REST APIs. The difference between the two APIs is the following:

The Person Profile API returns the contact information of the person who is speaking to the Alexa device. For more details, keep reading this page.
The Customer Profile API returns the contact information 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 Customer Profile REST API Reference.

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

Prerequisites

To protect user data, any skill that uses recognized speaker contact information must meet the following requirements. If Amazon determines that your skill violates any of these requirements, Amazon will reject or suspend your submission and notify you at 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 on 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. 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 REST API every time the customer invokes the skill with a request that needs this information.

Any of the requested information, such as name or phone number, might not be available to your skill when requested. Your skill code should handle missing information gracefully.

Steps to request recognized speaker contact information

To request recognized speaker contact information within your skill, perform the following steps:

Configure permissions for contact information.
Request contact information.
Request consent for contact information (Optional).
Test as you develop your skill.

Step 1: Configure permissions for contact information

Follow these steps to configure skill permissions to support personalization and recognized speaker contact information.

To configure personalization and recognized speaker contact information permissions in the Alexa developer console

Navigate back to your skill in the Alexa developer console.
Or, if you closed the skill page, follow these steps to find your skill.
1. Sign in to the Alexa developer console.
2. On the Skills tab, under SKILL NAME, find your skill.
3. Under ACTIONS, from the drop-down menu in your skill's row, select Edit.
Navigate to Build > TOOLS > Permissions.
Toggle on Skills Personalization.
You must enable this setting to use voice IDs in your skill.
Select one or more of the following permissions depending on which resources you require for your skill:
- Customer Name > Full Name
- Customer Name > Given Name (the user's first name)
- Customer Phone Number
You can select Full Name or Given Name, but not both.

Note: For the ja-JP locale, if you select Given Name, the Full Name of the user is returned, and the user sees full name in their Alexa app.

Step 2: Request contact information

Use the Person Profile REST API to get the requested contact information for the recognized speaker.

Alexa includes the context.System.apiAccessToken on all requests to your skill, regardless of whether the user granted your skill the permissions needed to fulfill the request for recognized speaker contact information. Therefore, you can't use the presence of apiAccessToken to determine whether you have the necessary permissions to obtain the contact information. Instead, include the apiAccessToken value in the API request and check the response code. An HTTP 403 Forbidden response indicates that your skill doesn't have the necessary permissions. Make sure that your skill handles the situation gracefully if the customer refuses to grant permission to access contact information.

Note: Don't store the token because it expires. Instead, obtain the apiAccessToken value from each subsequent request.

Step 3: Request customer consent for contact information (Optional)

When a customer enables a skill that requires customer permissions, the Alexa app prompts the customer to consent to provide the requested permissions. If the customer chooses not to grant these permissions during skill enablement, your skill can send prompt the user during the skill session for the permissions required for the skill.

You request consent by sending a permissions card in the response to Alexa. When you include the AskForPermissionsConsent card in the response, Alexa speaks to the user to tell them to view the card in the Alexa app or on an Alexa-enabled device with a screen. The voice prompt that your skill provides should describe why the skill needs these permissions. The user can decide whether to grant the requested permissions.

If possible, you should develop your skill so that some functionality is available without the requested permission and prompt the user for permissions when needed to fulfill a user request.

Permission scope

Include the requested permission scope for recognized speaker contact information in the permissions card. The permissions value always matches the scope that you declared for the skill on the Build > Permissions page in the developer console.

For details about the permissions card, see Send a card to ask for customer permission.

Permission scope	Description
`alexa::person_id:read`	Allows your skill to use Voice IDs.
`alexa::profile:name:read`	Allows your skill to get the full name of the recognized speaker.
`alexa::profile:given_name:read`	Allows your skill to get the given first name of the recognized speaker.
`alexa::profile:mobile_number:read`	Allows your skill to get the mobile phone number of the recognized speaker.

Permissions card example

The following is a sample response for a card with a request for name and phone number.

{
  "version": "1.0",
  "response": {
    "card": {
      "type": "AskForPermissionsConsent",
      "permissions": [
        "alexa::profile:name:read",
        "alexa::profile:mobile_number:read"
      ]
    }
  }
}

Permission events

Use Skill Permission Accepted events in your skill so that your skill is notified when the customer has granted permissions to the skill.

If you want Alexa to notify your skill when the customer grants or revokes permissions, you can subscribe to the following skill events:

Skill permission accepted event – Your skill receives this event when a customer accepts permissions the first time, or grants permissions after revoking all the permissions.
Skill permission changed event – Your skill receives this event when a customer grants additional permissions to a skill, or revokes the existing permissions from a skill.

Skill permissions events for changing or granting permissions always include the most recently accepted permissions in the payload. For details about using skill events, see Skill Events in Alexa Skills.

Step 4: Test as you develop your skill

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

You can do limited testing on the Test page in the Alexa developer console, using yourself as the skill user. When you test your skill with the Alexa Simulator, your skill can call the Person Profile API and receive a non-error response that contains your own information. You can also test the flow in which the user doesn't grant permissions.

To test what happens when a user has provided permissions to your skill, make sure that you have granted the contact permissions for your skill in the Alexa app. When you open the skill, Alexa sends a LaunchRequest with the apiAccessToken that includes the permission.

To test what happens when a user hasn't provided permissions to your skill, make sure you haven't granted, or that you have revoked, contact permissions for your skill in the Alexa app. When you open the skill, Alexa sends a LaunchRequest with the apiAccessToken value that doesn't specify the correct permissions. If your skill passes this token to the Person Profile API, the API returns a HTTP 403 Forbidden status code.

Best practices when contact information is unavailable

As a developer, you can determine the appropriate response when your customer doesn't grant permission or doesn't provide recognized speaker contact information. You can provide a graceful fallback message that indicates that the skill can't function without this information, and then end the session. Or, you can provide a message that indicates that the skill continues to work, but with reduced functionality.

Keep in mind the following best practices 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. The prompt that your skill provides should describe why the skill needs these permissions.
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.
Prepare 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 HTTP 204 No Content status. In this situation, if your skill can't fulfill the request without some piece of information, you might 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, make sure that you consider the skill workflow for all the scenarios in which you fail to get the desired information.

Was this page helpful?

Provide feedback

Last updated: Mar 20, 2024