Use the Name-free Interaction Toolkit in SMAPI

Updating the Interaction Model using SMAPI

Use SMAPI to tell Alexa which skill launch phrases and intent launch phrases you want the customer to be able to say to access your skill more naturally. When you specify a skill launch phrase, you give the customer a new way to open your skill without using the typical invocation pattern, like telling Alexa to open or launch the skill. When you specify an intent launch phrase, you give the customer a way to launch right into a particular intent within your skill, again without using the typical invocation pattern.

Place the _nameFreeInteraction container within the interaction model. Identify each intent that you want to make available for name-free interaction.

For a skill launch phrase, which is where an IngressPoint launches your skill as a modal launch, set the type field LAUNCH with no name field. Use the format RAW_TEXT and set the value to your skill launch sample utterance. The sample utterance must not contain slots and should be a complete phrase. In your skill, specify up to five skill launch phrases.

For an intent launch phrase, which is where an IngressPoint launches into a specific intent for your skill, set the type field to INTENT and the name field to the existing intent name, as defined in language model for the skill. Use the format RAW_TEXT and set the value to your intent launch sample utterance. The sample utterance must not contain slots and should be a complete phrase. For each IngressPoint, specify up to five intent launch phrases.

An example interaction model with _nameFreeInteraction container is available below.

Example

{
  "interactionModel": {
      "languageModel": {},
      "_nameFreeInteraction": {}
  }
}

Sample

{
  "interactionModel": {
    "languageModel": {
      "invocationName": "XYZ 101.8",
      "intents": [
        {
          "name": "PlayGenreIntent",
          "samples": [
            "play jazz music",
            "play classical music",
            "jazz",
            "classical",       
          ]
        }
      ]
    },
    "_nameFreeInteraction": {
      "ingressPoints": [
        {
         "type": "LAUNCH",
         "sampleUtterances": [
           {
             "format": "RAW_TEXT",
             "value": "Launch Seattle's XYZ radio"           
           },
           {
             "format": "RAW_TEXT",
             "value": "Launch Seattle's 101.8"           
           }
         ]
        },
        {
          "type": "INTENT",
          "name": "PlayGenreIntent",
         "sampleUtterances": [
           {
             "format": "RAW_TEXT",
             "value": "play jazz music"           
           },
           {
             "format": "RAW_TEXT",
             "value": "play classical music"           
           }
         ]
        }               
      ]   
    }
  }
}

SMAPI users will update the interaction model as you do today through the API endpoint using the following operations.

GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}

For more about how to update the interaction model using SMAPI, refer to Interaction Model Management.

Build Interaction Models

Post authoring, you should be able to validate, build and test their skills (en-US only) for name-free interactions. Use existing command for triggering builds PUT /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}

GET /v1/skills/{skillId}/status?resource={resource1}&resource={resource2} Retrieves the build status of the specified model. For builds of IMs containing NFI container, get-model-status should also include the status of NFI builds

SkillStatus: {
  "interactionModel": {
    "en-US": {
      "eTag": "agasguhq34894hjk",
      "lastUpdateRequest": {
        "status": "SUCCEEDED",
        "errors": [],
        "warnings": [],
        "buildDetails": {
          "steps": [
            {
              "name": "LANGUAGE_MODEL_QUICK_BUILD",
              "status": "SUCCEEDED"
            },
            {
              "name": "LANGUAGE_MODEL_FULL_BUILD",
              "status": "SUCCEEDED"
            }
            {
              "name": "DIALOG_MODEL_BUILD",
              "status": "SUCCEEDED"
            }
           {
             "name": "NAME_FREE_INTERACTION_BUILD",
             "status": "IN_PROGRESS | SUCCEEDED | FAILED"
           }
          ]
        }
      }
    }
  }
}

Testing Name Free Interaction in Isolation (en-* only)

After building a skill, consider testing your skill in isolation with name-free utterances to help you understand the user experience when Alexa invokes your skill by using name-free interaction. Keep in mind that testing in isolation isn't required for certification of your skill.

Testing in isolation means the simulation tool considers only the intents in the development-stage interaction model. In isolation, Alexa routes the name-free utterance to your skill. The testing doesn't reflect actual routing decisions made by Alexa across all published skills and experiences. You might observe different outcomes in production because Alexa considers a variety of signals when routing name-free requests.

Typically, you would invoke your skills using the named invocation method:

User > ask “Joe’s horoscopes”, for the Cancer horoscope for today Alexa > Here is the horoscope for Cancer……

As part of NFI, you should be able to start simulations using name-free utterances for your skill's NFI participating intents, such as:

User > What is the horoscope for Cancer today? Alexa > OK, here is Joe’s horoscope Alexa > For Cancer, Mercury is no longer in retrograde, so….

If testing results in not mapping to any intent, be sure you have enough sample utterances for your intent and follow the guidelines for name free utterances found in the Do’s and Don’ts section. You should have at least 10 utterances for your intent. You can also try to adjust FallbackIntent sensitivity.

If you are finding that the simulation is mapping to the wrong intent, check for utterance conflicts, or update samples and slots to the right intent and remove conflicting samples in other intents that could be conflicting with the sample utterances.

Use preview ASK cli (ask) to test how a skill containing NFI intents behaves in isolated NFI testing.

You should first enable the skill that you will use in simulation. If you have not enabled the skill, you will receive the following error message “Skill is currently disabled in <development/live> stage. Please enable skill in order to call this API.”

For SMAPI use POST https://api.amazonalexa.com/v2/skills/<Skill Id>/stages/<Skill Stage>/simulations

In the request body to send simulation use:

Request Body {
	"input":{
		"content":"<Utterance Text>"
	},
	"device":{
		"locale":"<Locale>"
	},
	"session":{
		"mode":"<FORCE_NEW_SESSION / DEFAULT>"
	},
	"simulation":{
		"type":"<NFI_ISOLATED_SIMULATION>"
	 }
 }

To get simulation status use: GET https://api.amazonalexa.com/v2/skills/<Skill Id>/stages/<Skill Stage>/simulations/<Simulation Id>

Certification and NFI Model Training

Once you are satisfied with the changes to your interaction model, you will submit your skill for publishing. Amazon will review the interaction model updates in order to certify the skill.

Otherwise, you do not need to take any additional action to deploy the updated skill.

Upon publication, the name-free interaction model begins learning how to route traffic to your skill and intents. With the recurring training of Alexa machine learning and artificial intelligence, it might take up to eight weeks for Alexa to route name-free interaction utterances to your skills.

Troubleshooting

Common reasons for the build process to fail:

  • incorrect intent name
  • More than 5 skill launch phrases
  • More than 5 intent launch phrases per intent
  • Intent Launch Phrase is not part of intent’s language model
  • intent not included in language model
  • NFI Container does not have an ingress point field
  • NFI Container has ingress point field but the ingress point list is empty
  • Ingress point contains a null entry
  • Ingress point name is empty/blank
  • Ingress point does not have a valid type defined
  • Duplicate ingress points
  • Unsupported ingress points (Note: Built-In Intents are not supported)"
  • Name Free Interactions can only be added to published skills.
  • This skill is in an unsupported locale. Name Free Interactions are only available for English locales (en-US, en-GB, en-IN, en-CA, en-AU).
  • Mature rated skills are not allowed to use name free interactions
  • This skill is not eligible to receive name free invocations due to quality and engagement factors. These eligibility requirements might change in the future.
Was this page helpful?

Last updated: Apr 30, 2024