Add Personalized Greetings or Prompts

---

If your skill implements personalization for recognized speakers, and a recognized speaker with a voice ID has Personalize skills enabled in the voice ID settings in the Alexa app, then you can deliver a personalized greeting or a prompt for that recognized user. For more information about implementing personalization in your skill, see Add Personalization to a Skill.

• How greetings and prompts work
• How your skill says a recognized speaker's name
• Use SSML In your skill responses
• Use the alexa:name tag to say a recognized speaker's name
• Greetings and prompts error handling

How greetings and prompts work

If you implement personalized greetings or prompts in your skill, then Alexa can welcome the recognized speaker back to the skill with the speaker's name. This tells the speaker that Alexa recognizes them and confirms the personalization experience. You can construct your skill response using SSML and the alexa:name tag, and Alexa then inserts the recognized speaker's name into the response. Alexa does not share the speaker’s name with you without the speaker’s consent. If a user changes their name on their personal profile, then Alexa automatically uses the new name in the skill response.

How your skill says a recognized speaker's name

First, your skill service must extract the personId value from the speaker's request to Alexa. The personId field is nested in the context.System.person object. To see the full body of the request, see Request Format.

{
  "context": {
    "System": {
      "person": {
        "personId": "amzn1.ask.person.ABCDEF..."
      }
    }
  }
}

Example Node.js code to retrieve the person object and the personId field

Use SSML In your skill responses

For your skill to say the person's name in a response, you must configure your skill service to use SSML responses. For more information, refer to Speech Synthesis Markup Language (SSML) Reference–Use SSML.

Use the alexa:name tag to say a recognized speaker's name

When you want your skill to refer to a speaker's name, include the alexa:name tag in your response with these parameters.

Attribute	Value
type	Required. The type of name to speak. Available types: first: The first name (given name) of the user.
personId	Required. The personId value from the person object in the Alexa JSON request. <speak>Hi <alexa:name type="first" personId="amzn1.ask.person.ABCDEF..."/></speak> When Alexa receives this response, the user hears something like "Hi Jane," depending on the name they have configured in their Alexa app.

Skill response	What the user hears
<speak> Hi <alexa:name type="first" personId="amzn1.ask.person.ABCDEF..."/>, good morning. Here's your pancake recipe for breakfast today. </speak>	Alexa: Hi John, good morning. Here's your pancake recipe for breakfast today.
<speak> You got that, <alexa:name type="first" personId="amzn1.ask.person.ABCDEF..."/>. You are now ahead of <alexa:name type="first" personId="amzn1.ask.person.GHIJKLM..."/> by 10 points. <alexa:name type="first" personId="amzn1.ask.person.NOPQRS..."/>, you are next. Roll the dice. </speak>	Alexa: You got that, Lisa. You are now ahead of John by 10 points. Abby, you are next. Roll the dice.
<speak> Sure <alexa:name type="first" personId="amzn1.ask.person.ABCDEF..."/>. Getting you a ride from John's Ride Hailing account. </speak>	Alexa: Sure Mary. Getting you a ride from John's Ride Hailing account.

In the last example, "John" refers to the account holder and his third-party account that the skill uses to fulfill the user request.

Greetings and prompts error handling

If your skill response lacks a required value, contains an invalid value, or another error occurs, the skill endpoint receives a SessionEndedRequest error. This SessionEndedRequest object contains an error field that you might be able to use to debug the issue. In these instances, the skill user hears "There was a problem with the requested skill's response."

Example of an error for an invalid or missing personId parameter

{
  "reason": "ERROR",
  "error": {
    "type": "INVALID_RESPONSE",
    "message": "Speech with id amzn1.echo-api.request.xxxxx-yyyyy uses tag alexa:name, which requires the personId attribute to contain a valid personId"
  }
}

Example of an error for an invalid or missing type parameter

{
  "reason": "ERROR",
  "error": {
    "type": "INVALID_RESPONSE",
    "message": "Speech with id amzn1.echo-api.request.xxxxx-yyyyy uses tag alexa:name, which requires the type attribute to contain a valid type"
  }
}

Example of an error if the person represented by the provided personId disabled the Personalize skills toggle

{
  "reason": "ERROR",
  "error": {
    "type": "INVALID_RESPONSE",
    "message": "Speech with id amzn1.echo-api.request.xxxxx-yyyyy uses the following invalid personId attribute values for the alexa:name tag: [amzn1.ask.person.ABCEDF..., ...]"
  }
}

Your skill service code should incorporate error handling for these scenarios. See Add Personalization to Your Skill.

---

---

Last updated: Nov 29, 2023