Add Personalization to Your Alexa 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 don't 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.

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 ID, 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.
  • If your skill is a HIPAA–eligible skill then it must only use personalization as defined in Requirements for Skills that are HIPAA-Eligible.

Skill personalization for recognized speakers isn't available for the following use cases.

  • If your skill is child-directed, you can't use personalization.
  • Don't use personalization to handle sensitive user information.
  • Personalization isn't authentication. You can't rely on personalization when it's 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 ID 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 details about account linking, see Add Account Linking to Your Alexa Skill.

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

Not all users 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. 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.

By contrast, your skill can acquire recognized speaker information through the Person Profile API. The recognized speaker must have a voice ID and Personalize skills enabled in the Alexa app.

As the developer, you're responsible for complying with legal requirements regarding the capture and use of personal information. You can 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 ID 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 context.System.person object in the skill request.
  • The skill has a workflow that provides personalized skill responses based on the context.System.person.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. For more details about how an Amazon account holder can enable or disable Personalize skills for recognized speakers, see Manage skill personalization as a user.

  • If the speaker is recognized, the speaker has a voice ID, 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 context.System.person object with the personId identifier.
  • If the speaker isn't recognized or if Personalize skills isn't enabled for their voice ID in the Alexa app, the skill follows a workflow that doesn't provide personalized responses for the speaker.

A speaker can revoke skill personalization permission by disabling Personalize skills for their voice ID 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're 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 isn't recognized, or a user refuses permission for personalization.

Distinction between user and person in skill requests

Each skill request to Alexa includes a context.System.user object that contains a userId value. This userId value represents the registered Amazon account that's 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 context.System.user object, each skill request also includes a context.System.person object. Your skill service can use the personId value from the person object to provide responses personalized to that recognized speaker. The authenticationConfidenceLevel object in the person object represents the confidence of Alexa in the identity of the 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 context.System.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.

Authentication confidence levels for skill personalization

The authentication confidence level indicates how confident Alexa is in the identity of the speaker. If Alexa recognizes the speaker, the authentication confidence level is in the authenticationConfidenceLevel object within the context.System.person object. Authentication confidence levels below 400 indicate that the speaker was identified by their voice. Level 400 indicates that the identity of the speaker was confirmed by both a profile PIN and voice recognition. For details, see PIN Confirmation for Alexa Skills. The AuthenticationConfidenceLevel object is only passed to the skill if Alexa recognizes the speaker.

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 context.System.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...",
          "authenticationConfidenceLevel": {
             "level": 300
          }             
        }
      }
    },
    "request": {...}
 }

If Alexa doesn't recognize the speaker, or if the user didn't enabled personalization, the skill request doesn't include the context.System.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 context.System.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 context.System.user object also includes an accessToken field. Here, 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 ID, 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|<accessToken1>"
        },
        "person":  {          
          "personId":  "amzn1.ask.person.DEF456...",      
          "accessToken": "Atza|<accessToken2>",
          "authenticationConfidenceLevel": {
             "level": 300
          }           
        }
      }
    },
    "request": {...}
}

Code to retrieve the user and person objects

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

let user = context.System.user;

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

let person = 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 context.System.person object, if present in the skill response, to personalize skill responses when appropriate.
  • If the person object isn't present, either proceed with a workflow that doesn't include personalization at the speaker level, or exit gracefully.
  • If the user didn't 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 session.person.accessToken value is unique for each person. Otherwise, use the context.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 provide a general skill experience that doesn't require account linking, ask the customer to link the accounts by adding the Link Account card, or gracefully exit the session.

If your skill doesn't offer content that uses personalization, don't 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 don't use account linking can ignore accesstoken fields in these scenarios and just focus on context.System.user.userId and context.System.person.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>",
        "authenticationConfidenceLevel": {
           "level": 300
        }            
      }
    }
  },
  "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>",
        "authenticationConfidenceLevel": {
           "level": 300
        }             
      }
    }
  },
  "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>",
        "authenticationConfidenceLevel": {
           "level": 300
        }           
      }
    }
  },
  "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>",
        "authenticationConfidenceLevel": {
           "level": 300
        }           
      }
    }
  },
  "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's already live, you must thoroughly test your skill. For more information, see Test and Troubleshoot Personalization for Your Skill.

Set up your skill to request PersistentUnitId or PersistentEndpointId permissions

When you create or edit a custom skill, you can turn on permissions for PersistentUnitId and PersistentEndpointId 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 Read PersistentUnitId and/or Read PersistentEndpointId.

You can also edit the permissions in the skill manifest for your skill directly to add the personalization scope alexa::persistent_unit_id::read and/or alexa::persistent_endpoint_id::read if you're using SMAPI or the ASK CLI to build your skill.

Was this page helpful?

Last updated: Sep 10, 2024