Entity Resolution

Note: Sign in to the developer console to build or publish your skill.

Alexa uses entity resolution to resolve the user's utterance for a slot value to a single, known entity. An entity represents a real-world person, place, or thing. An entity can have an identifier that you can use in your code. Synonyms help Alexa resolve the user's utterance to a single entity.

For example, the user might say the value "holland" to fill a slot that collects the name of a country. Alexa resolves "holland" to the entity "Netherlands."

Note: This document assumes you are familiar with Alexa Skills Kit concepts such as intent, slot, and sample utterance. For more about these topics, see: About Intents, Slots, and Dialogs.

Slot types and entity resolution

The slot type for a slot determines how entity resolution works for that slot.

For a custom slot type, you define a set of entities, their identifiers, and the synonyms that resolve to the entity. For details about defining these elements, see Entity Resolution for Custom Slot Types.

For a built-in slot type, entity resolution depends on the specific built-in slot type:

A subset of built-in slot types fully support entity resolution and Alexa entities. For these types, Alexa defines the entities and their identifiers in the Alexa knowledge graph. You can use the Linked Data API to get data about these entities to use in your skill. For more about the Alexa knowledge graph and the built-in types that support Alexa entities, see Alexa Entities Reference.
For built-in slot types that you extend with your own values, entity resolution uses your custom values to define the entities, identifiers, and synonyms. For details about extending a built-in slot type, see Extend a Built-in Slot Type with Custom Values
For built-in slot types that don't support entity resolution and that you haven't extended with your own values, no entity resolution takes place. Alexa returns the value that the user spoke and doesn't return any entity resolution results.

For more about entity resolution for built-in slot types, see Entity Resolution for Built-in Slot Types.

Entity resolution results in the skill request

When users make requests to your skill, Alexa attempts to resolve the possible slot values in the utterance to known entities defined for the slot type. When entity resolution is successful, your skill gets the following information in the IntentRequest:

The actual value that the user spoke. Access this value in the slotValue.value property for the slot value.
An object containing an array of possible known entities. Each entity includes a name and ID. You can get the object with the results from the slotValue.resolutions property for the slot value.

The source of the possible entities and identifiers depends on the slot type as noted previously.

The resolutions property isn't included in the request when entity resolution doesn't take place.

The following example shows the entity resolution results for a slot that uses the custom slot type ListOfActivities. The user said "hiking" for the slot value. Alexa resolved this utterance to two possible entities: "hiking" and "snowshoeing," each with a custom ID. For brevity, this example shows the intent property of the IntentRequest.

{
  "intent": {
    "name": "PlanMyTripIntent",
    "confirmationStatus": "NONE",
    "slots": {
      "activity": {
        "name": "activity",
        "value": "hiking",
        "resolutions": {
          "resolutionsPerAuthority": [
            {
              "authority": "amzn1.er-authority.echo-sdk.amzn1.ask.skill.1.ListOfActivities",
              "status": {
                "code": "ER_SUCCESS_MATCH"
              },
              "values": [
                {
                  "value": {
                    "name": "hiking",
                    "id": "HIKE"
                  }
                },
                {
                  "value": {
                    "name": "snowshoeing",
                    "id": "SNOWSHOE"
                  }
                }
              ]
            }
          ]
        },
        "confirmationStatus": "NONE",
        "source": "USER",
        "slotValue": {
          "type": "Simple",
          "value": "hiking",
          "resolutions": {
            "resolutionsPerAuthority": [
              {
                "authority": "amzn1.er-authority.echo-sdk.amzn1.ask.skill.1.ListOfActivities",
                "status": {
                  "code": "ER_SUCCESS_MATCH"
                },
                "values": [
                  {
                    "value": {
                      "name": "hiking",
                      "id": "HIKE"
                    }
                  },
                  {
                    "value": {
                      "name": "snowshoeing",
                      "id": "SNOWSHOE"
                    }
                  }
                ]
              }
            ]
          }
        }
      },
      "toCity": {
        "name": "toCity",
        "confirmationStatus": "NONE",
        "source": "USER"
      }
    }
  }
}

Tip: The value and resolutions properties directly on the slot object are provided for backward compatibility. The preferred way to access slot values in the request is with the slotValue property. This property is available for slots that collect a single value and slots that collect multiple values.

For the full reference to the properties available on a request, see IntentRequest.

Authority for entity resolution results

Within the resolutions property, results are organized by authority. An authority represents the source for the data provided for the slot. The authority depends on the slot type:

Custom slot type – The authority is name of your custom slot type in the following format:

amzn1.er-authority.echo-sdk.<skill-id>.<CustomSlotTypeName>

The following example shows the authority for the custom slot type ListOfActivities used within a skill with the skill ID amzn1.ask.skill.1.

amzn1.er-authority.echo-sdk.amzn1.ask.skill.1.ListOfActivities
Built-in slot type that supports entity resolution – The authority is always AlexaEntities. The authority doesn't include the skill ID or slot type name.
Built-in slot type you have extended – The authority is the name of the built-in type, in the following format:

amzn1.er-authority.echo-sdk.<skill-id>.<BuiltinSlotTypeName>

The following example shows the authority for the extended AMAZON.Color slot type used within a skill with the skill ID amzn1.ask.skill.1.

amzn1.er-authority.echo-sdk.amzn1.ask.skill.1.AMAZON.Color

Entity resolution results from multiple authorities

Alexa returns entity resolution results for all of the authorities that might apply to a slot type. For example, you can extend a built-in slot that already supports entity resolution. Alexa attempts to resolve the user's utterance with both your custom values and the Alexa knowledge graph. The results for each type of entity resolution are provided in the request in the resolutionsByAuthority array.

For example, the AMAZON.City slot type supports entity resolution. Assume you extend the AMAZON.City slot type with some specific cities with IDs that you want to use in your code.

In this scenario, Alexa returns entity resolution results for two different authorities:

The authority amzn1.er-authority.echo-sdk.amzn1.ask.skill.1.AMAZON.City contains the results based on the custom values added to the AMAZON.City slot type. The type has been extended with a custom ID ("ORD") for the value "Chicago".
The authority AlexaEntities contains the results based on the Alexa knowledge graph. Alexa resolved the user's utterance to multiple possible entities, each with an IRI you can use to get information about the entity.

{
  "intent": {
    "name": "PlanMyTripIntent",
    "confirmationStatus": "NONE",
    "slots": {
      "activity": {
        "name": "activity",
        "confirmationStatus": "NONE",
        "source": "USER"
      },
      "toCity": {
        "name": "toCity",
        "value": "Chicago",
        "resolutions": {
          "resolutionsPerAuthority": [
            {
              "authority": "amzn1.er-authority.echo-sdk.amzn1.ask.skill.1.AMAZON.City",
              "status": {
                "code": "ER_SUCCESS_MATCH"
              },
              "values": [
                {
                  "value": {
                    "name": "chicago",
                    "id": "ORD"
                  }
                }
              ]
            },
            {
              "authority": "AlexaEntities",
              "status": {
                "code": "ER_SUCCESS_MATCH"
              },
              "values": [
                {
                  "value": {
                    "name": "Chicago",
                    "id": "https://ld.amazonalexa.com/entities/v1/1571475417946-62216896272364"
                  }
                },
                {
                  "value": {
                    "name": "Chicago River",
                    "id": "https://ld.amazonalexa.com/entities/v1/1571475417946-36988258397509"
                  }
                },
                {
                  "value": {
                    "name": "Chicago",
                    "id": "https://ld.amazonalexa.com/entities/v1/1571475417946-52020643901674"
                  }
                },
                {
                  "value": {
                    "name": "Chicago",
                    "id": "https://ld.amazonalexa.com/entities/v1/1571475417946-37512244375834"
                  }
                },
                {
                  "value": {
                    "name": "Chicago",
                    "id": "https://ld.amazonalexa.com/entities/v1/1571475417946-5265629940182"
                  }
                }
              ]
            }
          ]
        },
        "confirmationStatus": "NONE",
        "source": "USER",
        "slotValue": {
          "type": "Simple",
          "value": "Chicago",
          "resolutions": {
            "resolutionsPerAuthority": [
              {
                "authority": "amzn1.er-authority.echo-sdk.amzn1.ask.skill.1.AMAZON.City",
                "status": {
                  "code": "ER_SUCCESS_MATCH"
                },
                "values": [
                  {
                    "value": {
                      "name": "chicago",
                      "id": "ORD"
                    }
                  }
                ]
              },
              {
                "authority": "AlexaEntities",
                "status": {
                  "code": "ER_SUCCESS_MATCH"
                },
                "values": [
                  {
                    "value": {
                      "name": "Chicago",
                      "id": "https://ld.amazonalexa.com/entities/v1/1571475417946-62216896272364"
                    }
                  },
                  {
                    "value": {
                      "name": "Chicago River",
                      "id": "https://ld.amazonalexa.com/entities/v1/1571475417946-36988258397509"
                    }
                  },
                  {
                    "value": {
                      "name": "Chicago",
                      "id": "https://ld.amazonalexa.com/entities/v1/1571475417946-52020643901674"
                    }
                  },
                  {
                    "value": {
                      "name": "Chicago",
                      "id": "https://ld.amazonalexa.com/entities/v1/1571475417946-37512244375834"
                    }
                  },
                  {
                    "value": {
                      "name": "Chicago",
                      "id": "https://ld.amazonalexa.com/entities/v1/1571475417946-5265629940182"
                    }
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

Entity resolution status codes

When you get entity resolution results, the resolutions.resolutionsPerAuthority[].status.code property contains a status code that describes the results.

ER_SUCCESS_MATCH – The spoken value successfully resolved to a known entity.
- For a custom slot type, this means the value matched at least one value or synonym explicitly defined in the slot type
- For a built-in slot type that you extended, the value matched at least one value or synonym in the set of extended values you added.
- For a built-in slot type that supports entity resolution, the value resolved to at least one entity in the Alexa knowledge graph.
ER_SUCCESS_NO_MATCH – The spoken value didn't resolve to a known entity.
ER_ERROR_TIMEOUT – An error occurred due to a timeout.
ER_ERROR_EXCEPTION – An error occurred due to an exception during processing.

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023