We’ve changed our name! API.AI is now Dialogflow. Learn more here.


Entities are powerful tools used for extracting parameter values from natural language inputs. Any important data you want to get from a user's request, will have a corresponding entity.

The entities used in a particular agent will depend on the parameter values that are expected to be returned as a result of the agent functioning. In other words, a developer does not need to create entities for every possible concept mentioned in the agent – only for those needed for actionable data.

There are 3 types of entities: system (defined by Dialogflow), developer (defined by a developer), and user (built for each individual end-user in every request) entities. Each of these can be classified as mapping (having reference values), enum (having no reference values), or composite (containing other entities with aliases and returning object type values) entities.

Types of Entities

System Entities

System Entities are pre-built entities provided by Dialogflow in order to facilitate handling the most popular common concepts. Below are examples of the different types of system entities.

System Mapping

These system entities have reference values. For example, @sys.date matches common date references such as "January 1, 2015" or "The first of January of 2015" and returns a reference value in ISO-8601 format: "2015-01-01T12:00:00-03:00"

System Enum

These entities have no reference value. For example, @sys.color matches most popular colors and returns the matched color as it is without mapping it to any reference value. For example, shades of red, such as "scarlet" or "crimson", won't be mapped to "red" and will return their original values "scarlet" and "crimson".

System Composite

These entities can contain other entities with aliases and return object type values. For example, @sys.unit-currency is meant for matching amounts of money with indication of currency name, e.g., "50 euros" or "twenty dollars and five cents". It returns an object type value consisting of two attribute-value pairs: {"amount":50,"currency":"EUR"}

Developer Entities

You can create your own entities for your agents, either through web forms, uploading them in JSON or CSV formats, or via API calls.

Dev Mapping

These entities allow for the mapping of synonyms to a reference value. For example, a food type entity could have an entry with a reference value of "vegetarian" with synonyms of "veg" and "veggie".

To create a mapping entity, leave the checkbox Define Synonyms checked and add a reference value and synonyms.

Dev Enum

Enum type entities contain a set of entries that do not have mappings to reference values. Entries can contain simple words or phrases, or other entities.

To create an enum type entity, uncheck the Define Synonyms option and add entries.

Dev Composite

When an enum type entity contains other entities and they are used with aliases, we call it a composite entity. Composite entities are most useful for describing objects or concepts that can have several different attributes.

For example, a robot's movement can have two characteristics: direction and number of steps. In order to describe all possible combinations, we first need an entity that captures the direction.

Then we create a second entity that refers to the direction and the number of steps. Make sure to uncheck 'Define Synonyms'.

By providing the example "Move 10 steps forward", the @move entity is annotated automatically.

User Entities

User entities can be redefined on a session ID level, allowing for specific concepts, like a user's playlists.

See /userEntities for more information.

Batch Operations

You can move, copy, or delete multiple entities at once using batch operations.

To select multiple entities, click on the Entities section in the left menu, hover over the list and check one or more entities. This will reveal the options available for the selection. Choose the desired action and check the desired related options.

Operation Description
Copy This will keep the selected entities in the current agent, and move copies into the destination agent.
Move This option will remove the selected entities from the current agent, and move them into the destination agent

This will permanently delete the selected entities.

Additional options for copy and move operations include:

  • Copy related entities - This is generally an option you want to check, as it will move or copy entities used in the composite entities being affected.
  • Overwrite entities - This option will overwrite entities with the same name.

Export/Upload Entities


You can download entities in either JSON or CSV format. To do this, click on Entities in the left menu, hover over the entity, and click on the cloud/download icon cloud_download. This will prompt you to choose a format for the download.


You can upload entities in JSON or CSV format. To do this, click on Entities in the left menu, click on the More icon more_vert, then Upload entity and choose the file you want to upload.

JSON Format

The JSON file should correspond to the entity object format.

CSV Format

The CSV file should have the following format:

  • Each entry corresponds to a new line
  • The reference value and synonyms should be separated by commas
  • Each reference value and synonym should be enclosed in double-quotes
  • The reference value should be at the beginning of the line
  • Include the reference value twice of you want it to be matched by the entity

For example, this is an item in a CSV:

"New York City", "New York City", "NYC", "New York City, USA"

And this is the result, once uploaded to an agent:

Allow Automated Expansion

This feature of developer mapping entities allows an agent to recognize values that have not been explicitly listed in the entity.

If a user's request includes an item that isn't listed in the entity, Automatic Expansion recognizes the undefined item as a parameter in the entity. The agent sees the user's request is similar to the examples provided, so it can derive what the item is in the request.

For example, consider a shopping list with items to buy:

If a user says "I need to buy some vegetables", "vegetables" will be picked up as a value, even though it's not included in the @item entity. With Automated Expansion enabled, the NLU sees the user's query is similar to the User Says examples provided in the intent and can pick out what should be extracted as a new value.

The closer the user's input is to the examples provided in the User Says section, the better the results the Automated Expansion feature will provide. This is another reason to provide as many examples as possible.