Add Personalization to Your Skill

If your skill supports personalization, you can provide personalized experiences for recognized skill users. Alexa can also provide personalized greetings and prompts for recognized speakers, as described in Add personalized greetings or prompts.

This document specifically refers to personalization of skill experiences for recognized speakers. You can also personalize the skill experience in other ways that do not rely on recognizing the speaker, such as by obtaining the customer location or customer information from the Amazon account to which the currently active Alexa device is registered.

For a sample skill that demonstrates personalization for recognized speakers, see Skill Personalization Demo.

What is skill personalization?

An Alexa device might have two or more speakers who interact with it, and multiple devices might be registered to the same Amazon account. Each speaker who interacts with Alexa has different needs, preferences, and accounts on third-party apps. By default, a skill doesn't differentiate individual speakers, and therefore a skill can only personalize responses at the account level. Although a speaker can say, "Alexa, switch my account," to access their own account, not all speakers do this. Also, a speaker might not have their own separate Amazon account.

Without skill personalization for recognized speakers, if a skill has account linking to a third-party app, the skill is linked to only a single account, no matter which individual speaker interacts with the skill. With skill personalization, an individual skill user can link their individual account, and not use the shared account.

If your skill supports personalization, it can differentiate an individual user who has a voice profile, and who have the Personalize skills toggle enabled. For more information about how an Alexa user can enable or disable personalization, see Manage skill personalization as a user.

Consider ways that your skill can benefit if you provide content personalized on a per-speaker basis.

The following list shows examples of where personalization for recognized speakers could be helpful:

  • A transit skill might set up separate commutes for each speaker. The skill learns the specific commute for each recognized speaker, and provides content personalized to that speaker. For example, John might have a westbound commute that uses bus 554, and Jane might have a southbound commute that uses bus 124. When Jane asks the skill when she should leave for work, she gets a personalized response about bus 124.

  • An exercise skill might provide different fitness routines for each recognized speaker. For example, if Mary asks the skill for her fitness routine, she gets a different response than if John asks the skill for his fitness routine.

  • If Alexa recognizes a speaker, then a ride hailing skill, if that speaker has linked their account to the third-party app, can use that speaker's account when it orders a ride, rather than the account of the Amazon account holder.

Consider ways that your skill can benefit if you provide content personalized on a per-speaker basis.

Restrictions and implementation considerations

Keep the following considerations in mind as you develop personalization for your skill:

  • If your skill uses personalization for recognized speakers, your skill must have a privacy policy. Open your skill in the developer console and click Distribution. On the Distribution page, make sure you include a link to your privacy policy in the Privacy Policy URL box on the Distribution page for your skill. For more information, see Define Skill Metadata.
  • Skill personalization is only available for custom skills.

Skill personalization for recognized speakers is not available for the following use cases.

  • If your skill is child-directed, you can't use personalization.
  • If your skill uses information protected by HIPAA (Health Insurance Portability and Accountability Act), you can't use personalization.
  • Do not use personalization to handle sensitive user information.
  • Personalization is not authentication. You can't rely on personalization when it is essential to know the identity of a person.

Development and usage considerations for the skill developer and skill user

Skill personalization for recognized speakers requires specific actions on the part of both Alexa users and skill developers.

As a developer, you can set up your skill to provide personalized interactions for a recognized user and to account link with a speaker's individual third-party account even if it differs from the account held by the Amazon account holder for the device.

For example, for a ride-sharing skill, each user who has their own voice profile can link to their own account on a third-party app. Let's say John and Jane, who share an Alexa-enabled device, each link to their separate ride-hailing app accounts. The ride-hailing skill supports personalization, so Alexa can link to the correct user account in its personalized skill responses. Alexa can also use other user-specific information in its responses. For more information on account linking, see Understand Account Linking.

In some cases, due to factors such as sound quality, Alexa may not recognize a speaker who has a voice profile. In those cases, Alexa treats the speaker as a generic user for the Amazon account to which the device is registered.

Not all users will allow for skill personalization for recognized speakers. Your skill must have an adequate workflow to handle those situations.

Data privacy and usage of user information

Alexa might have access to user and speaker information that a skill doesn't have. For example, Alexa has personal information such as the name and phone number for an Alexa profile if the speaker has entered this information in the Alexa app. However, Alexa doesn't provide this personal information to third-party developers.

Your skill can acquire Amazon account holder information through the Customer Profile API, if the account holder consents in the Alexa app. However, the information that the Customer Profile API obtains relates to the account holder, and not to the current speaker. Thus, you can't use information obtained from the Customer Profile API to personalize responses for recognized speakers.

As the developer, you are responsible for complying with legal requirements regarding the capture and use of personal information. You may use personal information that you request only as permitted by the user and in accordance with your privacy notice and applicable law.

Checklist for personalization support in a skill

You must meet all of the following conditions for your skill to provide a personalized experience to a recognized speaker:

  • As the skill developer, you must have enabled the skill to request permissions for user consent for personalization. You can do this in the developer console, or you can update the permissions scope for personalization in the skill manifest for use with SMAPI or ASK CLI. The personalization scope is alexa::person_id:read.
  • The speaker's voice profile must have Personalize skills toggled on in the Alexa app.
  • Alexa recognizes a speaker by their voice, and based on this recognition, includes the corresponding person object in the skill request.
  • The skill has a workflow that provides personalized skill responses based on the personId value in the skill requests.

User requirements for skill personalization

In order for your skill to provide personalized responses, you must set up your skill to support personalization, as described subsequently in this document.

If your skill supports personalization, then the following sequence occurs when a user invokes your skill. Refer to Manage skill personalization as a user for more information on how an Amazon account holder can enable or disable Personalize skills for recognized speakers.

  • If the speaker is recognized, the speaker has a voice profile, and Personalize skills is enabled for that speaker, then the skill can provide personalized content to that speaker. Each subsequent skill request from that speaker, when recognized, includes a person object, and the skill service can parse the personId identifier from the skill request.
  • If the speaker is not recognized or if Personalize skills is not enabled for their voice profile in the Alexa app, the skill follows a workflow that does not provide personalized responses for the speaker.

A speaker can revoke skill personalization permission by disabling Personalize skills for their voice profile in the Alexa app at any time. Then the speaker's skill requests no longer include a person object, and the skill can't provide personalized responses for that speaker.

Your skill should have an operational workflow if the speaker doesn't provide personalization permissions or has revoked them. If your skill relies on personalization, and can't provide a skill experience otherwise, it should have a graceful exit.

Set up your skill to support personalization

To set up your skill to support personalization, you must follow these steps.

  1. Set up your skill to request personalization permissions.

    When you create or edit a custom skill, you can turn on permissions for Skill Personalization in the developer console.

    1. In the developer console, create or open your skill.
    2. Select the Build tab, and select Permissions at the bottom left.
    3. In the Permissions section, turn on the toggle for Skill Personalization.

    You can also edit the permissions in the skill manifest for your skill directly to add the personalization scope alexa::person_id:read if you are using SMAPI or ASK CLI to build your skill.

  2. Set up your skill service to use personalization in its responses, if Personalize skills is toggled on for a recognized user.

  3. Make sure your skill service gracefully handles those cases where a user is not recognized, or a user refuses permission for personalization.

Distinction between user and person in skill requests

Each skill request to Alexa includes a user object that contains a userId value. This userId value represents the registered Amazon account that is active on the device from which the speaker made the request. Alexa automatically generates this userId identifier when a user enables your skill on a device. If a user disables and re-enables a skill registered to the same account, the userId value changes, as does the personId value if available.

The individual speaking to Alexa might not be the same as the account holder to whom the device is registered. Thus, the userId value doesn't indicate who the speaker is, but instead indicates the Amazon account used to enable the skill. Your skill might not be able to provide content personalized to the current speaker based on the userId value.

With personalization, your skill can distinguish between individual speakers in the account. If all of the requirements for skill personalization have been met on both the skill development side and the recognized speaker side, then in addition to a user object, each skill request also includes a person object. Your skill service can use the personId value from the person object to provide responses personalized to that recognized speaker.

To summarize, the user object identifies the specific Amazon account, and the person object, if available, determines which recognized speaker is speaking to Alexa from that account. Alexa sends no personally identifying information about either the Amazon account holder or the current speaker without customer consent. A skill can distinguish between different personId values, and a skill can link skill requests that have the same personId value, but that doesn't provide personally identifiable information about the individual represented by the personId value.

If Alexa doesn't recognize a speaker, for whatever reason, the corresponding skill request for that speaker doesn't include a person object.

The basis of personalization is that your skill can recognize a unique personId value in the person object. Your skill can then use that to distinguish between different recognized users of the skill, as the personId value is unique for each of these speakers.

Skill request format with person object with no account linking

In the skill request, the context.System.person.personId field identifies the Alexa profile.

This request example includes the person object, but doesn't include account linking to a third-party application.

{
    "version": "1.0",
    "session": {...},
    "context": {
      ...
      "System": {
        ...
       "user": {
          "userId":  "amzn1.ask.account.ABC123..."
        },
        "person":  {          
          "personId":  "amzn1.ask.person.DEF456..."  
        }
      }
    },
  },
    "request": {...}
 }

If Alexa doesn't recognize the speaker, or if the user has not enabled personalization, the skill request doesn't include the person object.

Skill request format with a person object with account linking

A speaker can use account linking to link a third-party application account to either the device's Amazon account generally, or to their own Alexa profile in an account, or both.

Thus, if a recognized speaker has linked a ride-hailing application account to their Alexa profile, and that speaker invokes the corresponding skill to hail a ride, the request uses the recognized speaker's account, which means the person object also includes an accessToken field. The Amazon account owner might have also linked their ride hailing account with Alexa, in which case the user object also includes an accessToken field. In this case, the request includes accessToken values in both the user and person objects, as in the following example.

For example, if a recognized speaker has linked a ride-hailing application account to their voice profile, and that speaker invokes the corresponding skill to hail a ride, the request uses the recognized speaker's account. This means that the person object also includes an accessToken field. The registered Amazon account for the current device might also have its account linked to a ride hailing application account. In that case, the user object also includes an accessToken field. The request includes accessToken values in both the user and person objects. The context.System.person.personId field in the skill request distinguishes the Alexa profile.

{
    "version": "1.0",
    "session": {...},
    "context": {
      ...
      "System": {
        ...
       "user": {
          "userId":  "amzn1.ask.account.ABC123..."
          "accessToken": "Atza|IOUAOWERUOAUWERHUAHFASDF..."
        },
        "person":  {          
          "personId":  "amzn1.ask.person.DEF456...",      
          "accessToken": "Atza|DSBFHSVDFUSUFEDAANYQWTSA..."
        }
      },
    },
    "request": {...}
  }

Code to retrieve the user and person objects

The following example shows how to retrieve the user object in Node.js.

let user = request.context.System.user;

The following example shows how to retrieve the person object and the personId field in Node.js.

let person = request.context.System.person;
let personId = person.personId;

For each speaker, the personId value is different for each skill. In addition, if a speaker uses the same skill with different Amazon accounts on the same device, the personId value is different, although the skill and the speaker are the same. Alexa doesn't share personId information between skills or accounts.

For more information, see System object.

Adapt your skill service to support personalization

To support personalization for recognized speakers, your skill service must be able to handle the following cases.

  • Use the values in the person object, if present in the skill response, to personalize skill responses when appropriate.
  • If the person object is not present, either proceed with a workflow that doesn't include personalization at the speaker level, or exit gracefully.
  • If the user has not set up account linking, your skill can still provide a general skill experience that doesn't require account linking, or the skill can gracefully exit the session.
  • If your skill uses account linking, make sure that your skill accesses the correct user's account. Thus, if the person object is present, use the person.accessToken value. The System.person.accessToken value is unique for each person. Otherwise, use the System.user.accessToken value as a fallback. If neither accessToken value is available, then your skill should still provide a good experience to the user. Either your skill can either provide a general skill experience that doesn't require account linking, or ask the customer to link the accounts by adding the Link Account card, or the skill can gracefully exit the session.

If your skill doesn't offer content that uses personalization, do not enable Skills Personalization in the developer console, nor set up the personalization scope in the skill manifest.

Invocation request examples

In the following scenarios, John and Jane represent two skill users in the same household. Mary is a skill user in a different household. Each of these individuals has an Alexa profile in the same account in which their Alexa device is active. The accessToken values in these examples are placeholders, rather than actual values. Skills that do not use account linking can ignore accesstoken fields in these scenarios and just focus on userId and personId.

Two recognized speakers with separate third-party accounts

In this example, John and Jane are using a skill together, such as a game skill. The skill tracks John and Jane's responses separately with their respective personId tokens, and updates the user information accordingly in the skill's back-end system. The game skill has account linking at the Amazon account level.

In the first turn, John responds to the skill.

{
  "version": "1.0",
  "session": {...},
  "context": {
    ...
    "System": {
      ...
      "user": {
        "userId": "<Represents the active Amazon account for which the skill is enabled>", 
        "accessToken": "<Token representing third-party account linked to active Amazon account>", 
      },
      "person": {          
        "personId": "amzn1.ask.person.<Represents John's Alexa profile>",
        "accessToken": "<Token representing third-party account linked to John's Alexa profile>", 
      }
    }
  },
  "request": {...}
}

In the second turn, Jane responds to the skill. The person object changes to reflect that Jane is the current speaker. If the skill has a task related to the account linked to Jane's Alexa profile, the skill can use the System.person.accessToken in the request. Your skill service could also save John's System.user.accessToken from the first turn and reuse it for the entire skill session.

{
  "version": "1.0",
  "session": {...},
  "context": {
    ...
    "System": {
      ...
      "user": {
        "userId": "<Represents the active Amazon account for which the skill is enabled>", 
        "accessToken": "<Token representing 3P account linked to active Amazon account>" 
      },
      "person": {          
        "personId": "amzn1.ask.person.<Represents Jane's Alexa profile>",
        "accessToken": "<Token representing 3P account linked to Jane's Alexa profile>" 
      }
    }
  },
  "request": {...}
}

Recognized speaker with Alexa profile linked to third-party account, and Amazon account linked to third-party account

Assume that you have a ride hailing skill called Ride Hailing, with an accompanying third-party app. In this example, John has linked his personal Ride Hailing account to his Alexa profile. John has also linked the Amazon account for the device to his Ride Hailing account. If John makes a request, and Alexa recognizes his voice, then the skill request is as shown here.

{
  "version": "1.0",
  "session": {...},
  "context": {
    ...
    "System": {
      ...
      "user": {
        "userId": "<Represents the active Amazon account for which the skill is enabled>", 
        "accessToken": "<Token representing 3P account linked to active Amazon account>" 
      },
      "person": {          
        "personId": "amzn1.ask.person.<Represents John's Alexa profile>",
        "accessToken": "<Token representing third-party account linked to John's Alexa profile>" 
      }
    }
  },
  "request": {...}
}

Recognized speaker with their third-party account linked to Alexa profile, and a different third-party account linked to Amazon account

In this example, Jane has linked her personal Ride Hailing account to her Alexa profile. John has linked his Ride Hailing account to the active Amazon account for the device. Jane invokes the Ride Hailing skill and Alexa recognizes her voice. The following example shows the skill request.

{
  "version": "1.0",
  "session": {...},
  "context": {
    ...
    "System": {
      ...
      "user": {
        "userId": "<Represents the active Amazon account for which the skill is enabled>", 
        "accessToken": "<Token representing 3P account linked to active Amazon account>", 
      },
      "person": {          
        "personId": "amzn1.ask.person.<Represents Jane's Alexa profile>",
        "accessToken": "<Token representing 3P account linked to Jane's Alexa profile>", 
      }
    }
  },
  "request": {...}
}

Unrecognized customer (and the Amazon account holder has a third-party account linked)

In this example, Mary is a guest at John and Jane's house and invokes the Ride Hailing skill on their device. Alexa doesn't recognize Mary's voice. Therefore, because John's Ride Hailing account links to the active Amazon account for the device, the skill uses John's account, which is reflected in the user.accessToken value to book the ride. The following example shows the skill request.

{
  "version": "1.0",
  "session": {...},
  "context": {
    ...
    "System": {
      ...
      "user": {
        "userId": "<Represents the active Amazon account for which the skill is enabled>", 
        "accessToken": "<Token representing third-party account linked to account holder>", 
      }
    }
  },
  "request": {...}
}

Test how personalization works in your skill

Before you submit your skill for certification, for an unpublished skill, or deploy personalization-related changes for a skill that is already live, you must thoroughly test your skill. For more information, see Test and Troubleshoot Personalization for Your Skill.