Add Name-Free Interaction to Alexa Smart Properties Skills

When you create a skill for Alexa Smart Properties, you can add name-free interaction. Name-free interaction lets users ask Alexa for information about a property or its services without mentioning the skill by name. For example, a user can say, "Alexa, what's the visitor wi-fi password?" instead of "Alexa, ask {skill name} for the visitor wi-fi password." Name-free interaction enables your skill to provide the following functionality:

• Serve users property-specific information – For example, your skill might handle the following questions:
  • "Alexa, what is the Wi-Fi password?"
  • "Alexa, when is the dining room open?"
  • "Alexa, where is the pool?"
• Support staff by routing and fulfilling property-specific requests – For example, your skill might handle the following requests:
  • "Alexa, my door needs maintenance."
  • "Alexa, I need more pillows."
  • "Alexa, I lost my mail key."

The following sections describe requirements, best practices, and a list of steps to add name-free interaction to your Alexa Smart Properties skill.

Steps to add name-free interaction to your skill

To add name-free interaction to your skill, take the following steps:

1. Confirm that your skill meets the requirements
2. Choose use cases for name-free interaction
3. Update your interaction model
4. Get access to name-free interaction for your skill
5. Update skill manifest with name-free permission
6. Identify name-free interaction intents
7. (Optional) Implement the CanFulfillIntentRequest interface
8. Test your skill in development
9. Submit your skill for certification and publishing
10. Enable your Live skill in property
11. Monitor your skill

Step 1: Confirm that your skill meets the requirements

To support name-free interaction, your Alexa Smart Properties skill must meet the following requirements:

Information – Your skill cannot provide information that is irrelevant to your property or part of a select set of domains handled by Alexa such as the weather. For details, see Choose use cases for name-free interaction.

Interaction model – Your interaction model must be clear and concise. For details, see Update your interaction model.

Locales – Your skill may use any language or language pair supported by Alexa Smart Properties.

Step 2: Choose use cases for name-free interaction

As part of planning for adding name-free Interaction to your skill, you’ll want to pick 5-10 overarching use cases to focus your utterances (e.g. menus, dining, local suggestions, emergency notifications). This section provides an overview of the common use cases in each subscription (i.e., healthcare, senior living, and hospitality) as well as guidelines on what content your skill cannot provide with name-free interaction.

Not every interaction in your skill should be a name-free interaction. Prior to narrowing down your target use cases, consider the following best practices and work with your key stakeholders (i.e., staff) to ensure you are capturing in- demand content.

Starter Questions

To start, think about what your customers are actually asking for. While it may seem important to enable every possible permutation of a request, realistically customers tend to stick to the same common set of utterances. For example, residents in an independent living facility will ask "when is dinner" or "what is for dinner" but are rarely going to ask "what canapes are on the menu." Start with the essentials and work towards more granular requests.

• What are customers asking staff for? "When is my physical therapy appointment? "
• What are customers generally asking for repeatedly? "What is on the menu for lunch today? "
• What Alexa functionality is potentially difficult to navigate via voice? "I want to book a hair appointment. "
• In what scenarios is it important to be succinct/respond accurately? "I need help. "

Start with Collateral

You should have in-room collateral and/or training content for customers of your Alexa experience. Start with the sample utterances identified in that content and work backward.

Blocked Categories

While there is some functionality your skill may serve, the following categories are blocked for name-free interaction. You cannot choose use cases that fall into these categories.

• Smart Home ("Turn off the lights.")
• Music ("Play pop music.")
• Weather ("What's the temperature?")
• Time ("What time is it?")
• Timers ("Set a 15-minute timer.")
• Alarms ("Set an alarm for 6 AM.")
• Calling ("Call the front desk.")
• Audiobooks ("Read Harry Potter.")
• Video ("Play The Lost City.")
• Information unrelated to your property ("What's the news?")
• Alexa's opinions ("What's your favorite song?")
• Common intents ("Stop" "Pause" "Exit")

Sample Use Cases for Healthcare

Sample Use Cases for Hospitality

Sample Use Cases for Senior Living

Step 3: Update your interaction model

To maximize the accuracy of your interaction model, heed the following best practices when you design your interaction model:

• Provide a clear skill description.
• Use descriptive intent names. For example, CarBookingIntent is better than BookingIntent.
• Provide sample utterances that reflect the intent's meaning.
• Use real synonyms. For example, the noun "rental car" isn't the same as the action of "returning a car." Create a new slot for new words instead of treating them as synonyms.
• Include no more than two slot values in each sample utterance. For example, "Can you tell me about the {amenity}?" and "Can you tell me the {info type} of {amenity}?" are both acceptable. Avoid sample utterances such as, "{question_type} {verb} {quantifier} {info_type} {amenity}?"
• Provide answers that sound natural for Alexa to read out loud, including when a slot value is filled.
• (Optional) Include support for words that are spelled differently but are pronounced the same (for example, "gray" and "grey").

Make sure that your skill doesn't have the following characteristics:

• A slot value as a sample utterance (for example, "{Slot}").
• Intents that conflate concepts. For example, don't use one intent to describe both a location (for example, restaurant) and activities (for example, eat dinner). Instead, create one intent to describe the location ("Where can I find {location}?") and another to describe the activities ("Where can I {activity}?").
• Sample utterances as slot values. For example, don't list "{helpSlot}, where is the {helpSlot}?" as a sample utterance and list "I need some help" as a slot value.

The following example demonstrates a best-practice interaction model.

Example of a best-practice interaction model  

{
   "name": "InformationIntent",
   "slots": [
     {
        "name": "history",
        "type": "history_type"
     },
     {
        "name": "checkout",
        "type": "checkout_type"
     },
     {
        "name": "smoking",
        "type": "smoking_type"
     },
     {
        "name": "location",
        "type": "location_type"
     },
     {
        "name": "luggage",
        "type": "luggage_type"
     }
   ],
   "samples": [
     "can you tell me about {history}",
     "tell me when is {checkout}",
     "i would like to {smoking}",
     "do we have {location} included",
     "tell us where the {luggage} is"
   ],
   "types": [
     {
        "name": "history_type",
        "values": [
          {
            "name": {
               "value": "artwork",
               "synonyms": [
                  "artwork on the wall",
                  "art work",
                  "paintings",
                  "photos",
                  "sculpture",
                  "photo",
                  "painting",
                  "sculptures",
                  "mural",
                  "posters",
                  "art facts",
                  "artifacts",
                  "art if facts",
                  "art if acts",
                  "art if axe"
               ]
            }
          },
          {
            "name": {
               "value": "building history",
               "synonyms": [
                  "hotel",
                  "hotel building",
                  "resort architecture",
                  "building architecture",
                  "resort design",
                  "building design",
                  "design of building",
                  "design of the building"
                ]
             }
           }
         ]
      }
   ]
  .......
}

Find and remove duplicate utterances

Duplicate utterances are overlaps in phrases between two or more Intents. To increase the chance that your customer utterances route to the desired intent, you can use tools such as the Utterance Profiler to catch duplicate utterances and poor utterance coverage.

Example: "a painkiller"

A skill has two intents:

1. GetMedicineIntent for requests for medicine
2. NeedWaterIntent for requests for beverages.

The developer is using the built-in AMAZON.Drink slot to cover all possible beverages. Leveraging the built-in slots is a great way to cover variations on a phrase without the added effort of managing the slot yourself. The developer also has a custom slot for types of medicine.

However, when the developer uses the Utterance Profiler tool to test intent and slot resolution, the phrase "a painkiller" returns both intents.

So why is this a duplicate utterance? The from Utterance Profiler output has the value "Drink: painkiller" under the SLOT, indicating that "painkiller" is a recognized drink.

The developer would likely choose to leave these intents as is, since the correct intent was returned and the utility of the AMAZON.Drink slot outweighs the chance that this phrase routes incorrectly. However, there is a risk some requests may route to NeedWaterIntent.

Step 4: Get access to name-free interaction for your Alexa Smart Properties skill

Before you can add name-free interaction to your skill, you need to allowlist your developer account to enable the name-free interaction availability type for your skill manifest.

Refer to Enable features and permissions for your property skills.

Step 5: Update skill manifest with name-free permission

After you add your vendor ID to the allowlist, you need to update the skill manifest to indicate that your skill supports NFI requests from an Alexa Smart Properties unit. This step can only be completed using the ASK CLI.

• Ensure you have the ASK CLI installed on your computer.
• Pull the latest skill manifest.
• Open the manifest in a JSON editor of your choice.
• Update the custom section to include the following "nameFreeInteraction" availability permission.

"nameFreeInteraction": {
    "availability": ["PREFERRED"]        
}, 

• Save and push the updated manifest.

The following is a snippet of an example skill manifest with the name-free interaction availability type specified.

"custom": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:040623927470:function:sampleSkill"
        },
        "nameFreeInteraction": {
            "availability": ["PREFERRED"]        
        }, 
}

Step 6: Identify name-free interaction intents

To indicate that an intent is eligible for NFI, you need to add the intent to the Intent Launch Phrases. There are two methods for updating the Intent Launch Phrases:

1. Alexa Developer Console
2. Alexa Skills Kit Command-Line Interface

Alexa uses the name-free interaction container during model training to improve the routing of the specified name-free interaction utterances to your custom skill.

Adding Intent in the Developer Console In the developer console, navigate to Build > Invocations > Intent Launch Phrases. If you successfully updated your manifest, the + Add Intent button should now be available. Add all intents that should be eligible for NFI. You only need to add the intent name; you don't need to add sample utterances for the intent. When all intents are added, Save and Build the model.

Adding Intents in the Skill Interaction Model If you use the Alexa Skills Kit Command-Line Interface for skill development, you can add the Intent Launch Phrases directly to the skill interaction model JSON (e.g., skill.json). Add the _nameFreeInteraction object inside the interactionModel object. When compete, Save and Deploy the updated skill.

The following JSON shows a simplified interaction model with a name-free interaction container for skill interaction.

Example of an interaction model with a name-free interaction container  

{
   "interactionModel": {
      "languageModel": {
         "invocationName": "My Property",
         "intents": [
          {
            "name": " InformationIntent",
            "samples": [  ]
          }
         ]
      },
   "_nameFreeInteraction":
   {
      "ingressPoints": [
      {
         "type": "INTENT",
         "name": " InformationIntent",
         "sampleUtterances": [ ]
      }
      ]
    }
   }
}

(Optional) Step 7: Implement the CanFulfillIntentRequest interface

You can use CanFulFillIntentRequest to respond "No" to requests that you don't want your skill to fulfill. For example, you might use CanFulFillIntentRequest if your skill receives requests that might more appropriately be handled by Alexa. By responding "No" to CanFulFillIntentRequest, your skill has the option to reject an intent, thereby offering Alexa with an opportunity to route the request elsewhere.

If you implement CanFulFillIntentRequest, ensure that the CanFulFillIntentRequest duration for your skill is less than two seconds. Otherwise, your skill might not be able to answer users' requests. For details about the Duration metric, see AWS Lambda function metrics. If the duration is more than two seconds, optimize it by using the guidance in the AWS documentation at Operating Lambda: Performance optimization – Part 1 and Operating Lambda: Performance optimization – Part 2.

Step 8: Test your skill in development

You can test the In Development version of your skills by enabling the skill on a test unit in your Alexa Smart Properties property. Ensure you Save and Build your skill before enabling it on a unit. Refer to enable a skill.

Testing Best Practices

Ask at least one sample utterance from every intent in your skill. Try to ask Alexa the same question in many different ways to make sure you have enough sample utterances. For example, try adding "please" or "some" to your questions. If Alexa doesn't pick your skill, update your sample utterances. If you have problems, see Troubleshooting.

Test that your skill has the following characteristics:

• Always listens for an answer after it asks a question.
• Provides helpful answers even if the provided information is unexpected. For example, if your skill hears a letter when it expects a number, your skill might say, "Hmm, I didn't get that. How many visitors are you expecting?" If your skill still doesn't get a number, your skill might answer, "Hmm, I didn't get that. Say 'Alexa, call the front desk' to connect with our staff."
• Doesn't answer questions unrelated to the property or the local area.
• Always respects basic commands such as "Exit."

Resolving recognition errors from Automatic Speech Recognition (ASR)

Automatic Speech Recognition is a service that takes the voice audio and translates that into text. As with interactions between two people, sometimes a word is misheard.

For example, the letter "b" is often heard as the letter "d".

ASR misrecognitions are due to many factors such as the customer’s accent, how close one word is to another (e.g., homophones like pear and pair), and environmental noise. The only way to catch these errors is to test with a human voice (synthetic voices like AWS Polly do not reliably trigger an ASR error).

Test with Echo Device or Amazon Developer Console

If you notice that utterances are consistently failing, there are two methods to try to determine what Alexa heard. The easiest method is using the Test section of the Amazon Developer Console. Just hold down the microphone icon in the input field and say the utterance.

For example, the phrase "tell Jillian hello" is accurately converted from speech to text. However, the phrase "ask Jillian for help" misrecognizes the name Jillian as Julian.

If a failing phrase is critical for your users, add in variations to the sample utterances for the target Intent. For the previous example, you should add "Julian" as a synonym for "Jillian" in the skill interaction model.

Step 9: Submit your skill for certification and publishing

You must publish your skill before the Alexa team can begin the training for name-free interaction availability in a production property. Contact your Amazon Solutions Architect to get started with certification.

Step 10: Enable your Live skill in property

Once your skill completes certification and publishes live, you can enable the skill on a property with the name-free interaction attribute. Refer to enable a skill.

Step 11: Monitor your skill

Use the Alexa developer console to generate skill metrics reports.

For example, you can review the intent history in the developer console. This report displays aggregated, anonymized frequent utterances (for example, used by 10+ guests) that were routed to your skill. This data shows you how users interact with your skill so that you can identify improvements you want to make to your skill.

Troubleshooting

If you have problems testing your skill for name-free interaction, review these troubleshooting solutions. If you still have problems, contact your Alexa solution architect.

Issue: The skill isn't enabled

Symptoms

Your skill doesn't answer questions. For example, you ask, "Alexa, what's the visitor wi-fi password?" and Alexa responds with, "{Skill name} can help with that. Only the owner can enable skills on this device." This reply means that the skill isn't enabled for the property.

Try this

Enable the skill on the Alexa-enabled device that you use to test your skill.

Issue: The utterance isn't included in the skill interaction model or the intent isn't included in the name-free interaction container as an ingress point

Symptoms

Alexa doesn't invoke your skill to handle a name-free utterance.

Try this

Verify that the utterance exists as a sample utterance for an intent that your name-free interaction defines as an ingress point.

Issue: Your skill isn't enabled for name-free interaction

Symptoms

Your skill only answers questions if you open the skill by name. For example, your skill doesn't respond to "Alexa, help me check out," but does respond to "Alexa, open {skill name} and help me check out."

Try this

Contact your Alexa solution architect to enable name-free interaction for your skill.

Issue: Your skill doesn't respond "No" to CanFulfillIntentRequest

Symptoms

Your skill answers questions that are unrelated to a property or local services.

Try this

Update your skill's response to CanFulfillIntentRequest to "No." For tips, see Understand Name-Free Interactions.

Issue: CanFulfillIntentResponse exceptions

Symptoms

Your skill gets CanFulfillIntentResponse exceptions.

Try this

Create integration tests for your skill.

Issue: An utterance doesn't have a slot value

Symptoms

Your skill doesn't receive traffic for a sample utterance.

Try this

Revise the sample utterance to include a slot value and slot. Clear slot values increase the probability that Alexa sends a question to your skill.

Issue: Your skill's CanFulfillmentResponse takes more than two seconds to respond

Symptoms

Your skill responded "Yes" to CanFulfillmentResponse, but Alexa didn't invoke the skill to handle the subsequent name-free interaction utterance.

Try this

Verify that your skill responds quickly enough to a CanFulfillmentResponse request so that Alexa considers your skill for the response. If you use a Lambda function, use provisioned concurrency to prevent the Lambda cold-start issue. For details, see the AWS documentation at Operating Lambda: Performance optimization – Part 1 and Operating Lambda: Performance optimization – Part 2.

Issue: A recognized variation for an utterance is not in the skill interaction model

Symptoms

You have tried all other troubleshooting methods and your skill is still not receiving a request.

Try this

Verify that the heard utterance is in your interaction mode. Refer to Resolving errors from Automatic Speech Recognition (ASR).

Related topics

• Understand Name-Free Interactions
• About Designing an Interaction Model
• About Alexa Smart Properties

Last updated: Jan 26, 2024