Intents

An intent categorizes an end-user's intention for one conversation turn.

An intent contains the following data:

Term	Definition
Display name	Name displayed on the console for the intent.
Labels	Labels that help categorize intents. For example: head intent.
Training phrases	Training phrases are example phrases for what end-users might type or say, known as end-user input. When end-user input resembles one of these phrases, Conversational Agents (Dialogflow CX) matches the intent. You don't have to define every possible example, because Conversational Agents (Dialogflow CX)'s built-in machine learning expands on your list with other, similar phrases.
Parameters	You define your training phrases to use parameters to extract values from specific parts of the end-user input.
DTMF patterns	See DTMF for telephony integrations.

Intent matching

When an end-user enters input (text, speech, or telephone key-presses), Conversational Agents (Dialogflow CX) compares the input to intent training phrases to find the best match. This process is called intent matching. Intent matching can only occur for intents associated with an intent route (a state handler with an intent requirement) in scope.

Key-press input is matched according to DTMF patterns. When searching for a matching intent to text, however, Conversational Agents (Dialogflow CX) scores potential matches with an intent detection confidence, also known as the confidence score. These values range from 0.0 (completely uncertain) to 1.0 (completely certain). Once intents are scored, there are two possible outcomes:

• If the highest scoring intent has a confidence score greater than or equal to the classification threshold setting, it is returned as a match.
• If no intents meet the threshold, then a no-match event will be invoked.

Note: Conversational Agents (Dialogflow CX) ML models have some level of case sensitivity, which might result in slightly different match scores for end-user inputs that differ only in capitalization. The advanced NLU model is case-sensitive, while the standard NLU model is not. See more in the agent design best practices guide.

Training phrases

Note: There are many important best practices for training phrases described in the agent design best practices guide.

Training phrases are example phrases for what end-users might type or say, referred to as end-user input. For each intent, you create many training phrases. When an end-user input resembles one of these phrases, Conversational Agents (Dialogflow CX) matches the intent.

For example, the training phrase "I want pizza" trains your agent to recognize end-user input that is similar to that phrase, like "Get a pizza" or "Order pizza".

You don't have to define every possible example, because Conversational Agents (Dialogflow CX)'s built-in machine learning expands on your list with other, similar phrases. You should create at least 10-20 (depending on complexity of intent) training phrases, so your agent can recognize a variety of end-user inputs. For example, if you want your intent to recognize an end-user's input about their favorite color, you could define the following training phrases:

• "I like red"
• "My favorite color is yellow"
• "black"
• "Blue is my favorite"
• ...

Annotate training phrases

Note: There are many important best practices for training phrase annotations described in the agent design best practices guide.

You control how end-user data is extracted by annotating parts of your training phrases and configuring the associated parameters.

For example, consider a training phrase like "What is the forecast tomorrow for Tokyo?" You should annotate "tomorrow" with a date parameter and "Tokyo" with a location parameter. When you annotate parts of a training phrase, Conversational Agents (Dialogflow CX) recognizes that these parts are just examples of actual values that will be provided by end-users at runtime. For an end-user input like "What is the forecast on Friday for Sydney?", Conversational Agents (Dialogflow CX) would extract the date parameter from "Friday" and the location parameter from "Sydney".

You must annotate all training phrase parts that are meant to be extracted as parameters. Otherwise, Dialogflow will not extract the values.

When building an agent with the console, most annotations are automatically created for you when you add training phrases that contain parts that can be matched to an existing entity type. These parts are highlighted in the console. You can edit these annotations and parameters as needed.

To manually annotate a training phrase with the console:

1. Select the part of the training phrase that you want to annotate.
2. Select the desired entity type from the list.
3. A parameter is created for you in the parameter table below.

When building an agent with the API, you must annotate training phrase parts manually. See the TrainingPhrase type used by the Intent type. Go to the Intent API reference

Select a protocol and version for the Intent reference:

Protocol	V3	V3beta1
REST	Intent resource	Intent resource
RPC	Intent interface	Intent interface
C++	IntentsClient	Not available
C#	IntentsClient	Not available
Go	IntentsClient	Not available
Java	IntentsClient	IntentsClient
Node.js	IntentsClient	IntentsClient
PHP	Not available	Not available
Python	IntentsClient	IntentsClient
Ruby	Not available	Not available

Close

Implicit entities created by training phrases

Note: You should define entities explicitly, rather than rely on implicitly defined custom entity values.

Most custom entities are defined explicitly by creating entity types and adding entity entries. However, custom entities may also contain implicit values. This happens when you annotate text of a training phrase, where the annotated text is not a value defined by the selected entity type. The annotated text becomes an entity reference value for the implicitly added entity entry. If the entity type is a map entity, the text also becomes a synonym for the entity entry.

Default welcome intent

When you create an agent, a default welcome intent is created for you. For some languages, the intent has simple training phrases like "Hi" or "Hello" that are meant to match initial end-user input. You can edit this intent as desired.

When using the API, you can reference this intent with the following intent ID:

00000000-0000-0000-0000-000000000000

If your agent initiates the conversation, you can trigger this intent using the API. Use the value projects/<PROJECT_ID>/locations/<LOCATION_ID>/agents/<AGENT_ID>/intents/00000000-0000-0000-0000-000000000000 in the QueryInput.intent.intent field when calling the detectIntent or streamingDetectIntent method.

Default negative intent

When you create an agent, a default negative intent is created for you. You can add training phrases to this intent that act as negative examples. There may be cases where end-user input has a slight resemblance to training phrases in normal intents, but you do not want these inputs to match any normal intents.

For example, a room booking agent may have a training phrase like "I'd like to book a room". If the end-user wants to purchase a book about rooms, they may say "I'd like to buy a book about rooms." To ensure that the end-user input does not match your intent, you can add that phrase as a negative example.

In addition, you should add possible phrases that are out of scope for the agent, so they will not match any intent. However, avoid adding a very large quantity of these phrases. For example, if you define 10,000 default negative intent phrases, this negatively impacts normal intent matching.

You should regularly review these phrases, as some of these phrases may have been originally out of scope for the agent, but were subsequently added to intents.

The default negative intent has impact across all intent matching. Phrases you add to it could benefit matching for one intent but harm matching for another. For example, you might add "international calling" to the default negative intent to avoid matching an international travel intent. However, this will also prevent that phrase from matching an international calling intent.

When using the API, you can reference this intent with the following intent ID:

00000000-0000-0000-0000-000000000001

Cancel intents

During a conversation, the end-user may want to cancel the current conversation topic. For example, the currently active page may be asking for a date for a new appointment, but the end-user has decided against creating a new appointment. The end-user may say something like "cancel" or "I do not want a new appointment". To handle this situation, you can create one or more cancel intents for your agent. You can name these cancel intents anything you like, but it is customary to include "cancel" in the name. You should associate these cancel intents with intent routes that are in scope at relevant points in the conversation. These intent routes should transition to an appropriate page to handle the cancellation.

The training phrases for cancel intents should handle both generic and topic-specific attempts to cancel. For example:

• Cancel
• Stop
• I changed my mind
• Nevermind
• Take me back
• Go back
• I do not want a new appointment
• Cancel new appointment
• Delete new appointment

Create an intent

To create an intent:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Intents.
6. Click +Create.
7. Enter intent data.
8. Click Save.

API

See the create method for the Intent type. Go to the Intent API reference

Select a protocol and version for the Intent reference:

Protocol	V3	V3beta1
REST	Intent resource	Intent resource
RPC	Intent interface	Intent interface
C++	IntentsClient	Not available
C#	IntentsClient	Not available
Go	IntentsClient	Not available
Java	IntentsClient	IntentsClient
Node.js	IntentsClient	IntentsClient
PHP	Not available	Not available
Python	IntentsClient	IntentsClient
Ruby	Not available	Not available

Close

Delete an intent

To delete an intent:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Intents.
6. Hover your mouse over the intent you want to delete.
7. Click the delete button.

API

See the delete method for the Intent type. Go to the Intent API reference

Select a protocol and version for the Intent reference:

Protocol	V3	V3beta1
REST	Intent resource	Intent resource
RPC	Intent interface	Intent interface
C++	IntentsClient	Not available
C#	IntentsClient	Not available
Go	IntentsClient	Not available
Java	IntentsClient	IntentsClient
Node.js	IntentsClient	IntentsClient
PHP	Not available	Not available
Python	IntentsClient	IntentsClient
Ruby	Not available	Not available

Close

Access intent data

To access intent data:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Intents.
6. Click the intent you want to access.
7. View or update intent data.
8. Click Save to save any changes.

API

See the get and patch/update methods for the Intent type. Go to the Intent API reference

Select a protocol and version for the Intent reference:

Protocol	V3	V3beta1
REST	Intent resource	Intent resource
RPC	Intent interface	Intent interface
C++	IntentsClient	Not available
C#	IntentsClient	Not available
Go	IntentsClient	Not available
Java	IntentsClient	IntentsClient
Node.js	IntentsClient	IntentsClient
PHP	Not available	Not available
Python	IntentsClient	IntentsClient
Ruby	Not available	Not available

Close

Intent suggestions

Note: This feature is currently only available in the global and us-central1 regions. If you need this feature for other regions, contact your Google Cloud account team.

Note: Intent suggestions must be enabled in general agent settings.

Dialogflow automatically analyzes no-match occurrences during conversations and can suggest new intents or recommend additional training phrases for existing intents. Accepting these suggestions can help avoid future no-match occurrences.

When using suggestions, you can adjust the Cluster Size. Smaller values of cluster size suggests more intents with fewer training phrases per intent. Larger values of cluster size suggests fewer intents with more training phrases per intent.

To accept intent suggestions:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Intents.
6. Click the Suggestions tab.
7. Adjust the Cluster Size as desired.
8. Select a suggestion.
9. Select the training phrases you desire.
10. For the target intent, add the training phrases to an existing intent or a new one.
11. Click Save or Create New to save any changes. When you accept intent suggestions, the intent remains in the suggestion list.

Split intents

You can split one intent into two intents using the console. The interface allows you to select training phrases from a source intent and move them to a new intent:

Console

1. Open the Dialogflow CX console.
2. Choose your project.
3. Select your agent.
4. Select the Manage tab.
5. Click Intents.
6. Select the intent you want to split.
7. Click Split.
8. Select intents from the source intent.
9. Click Move right.
10. Provide other details for the target intent.
11. Click Split.

Compare and merge intents

You can compare or merge two intents to a single intent using the console:

Console

1. Open the Dialogflow CX console.
2. Choose your project.
3. Select your agent.
4. Select the Manage tab.
5. Click Intents.
6. Select the two intents you want to compare or merge.
7. Click Compare.
8. The training phrases are shown side by side for comparison.
9. To merge the two intents, click Merge.

Export and import intents

You can export and import intents for sharing across agents.

One of the export format options is CSV, which has the following columns:

• Intent Display Name
• Language
• Phrase

Each entry contains either the display name, language and first training phrase; or just a training phrase for the previously declared intent. Dialogflow encodes annotations in exported training phrases, so that annotations are restored when importing. The format for this encoding is:

(annotated part)[entity, parameter]

For example:

Intent Display Name,Language,Phrase
Shirt Selection,en,I want a (green)[@sys.color, color] shirt
,,I would like a (yellow)[@sys.color, color] shirt
Store Hours,en,When are you open?
,,What are your hours?

When importing intents, there may be merge conflicts when the display name for an intent in your existing agent matches that of an imported intent. You can control the merge behavior when intent display names match by selecting one of the following:

• Replace existing intents: An imported intent overwrites any same-named intent in your existing agent.
• Rename and import as new intents: The imported intent is renamed by appending "_1" to the display name.
• Merge with existing intents: The training phrases of an imported intent are added to the existing intent. If the same training phrases exist, they will not be duplicated.
• Keep original intents: The existing intent remains unchanged, and the conflicting intent is ignored. Nonconflicting intents are imported.

To export intents:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Intents.
6. Select each intent you want to export.
7. Click Export selected intents.
8. Select the desired format and destination.
9. Click Submit.

To import intents:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Intents.
6. Click Import.
7. Select the source.
8. If there are any conflicts, a dialog window is shown which allows to select the merge behavior.
9. Click Submit.

Export and import training phrases

You can export and import training phrases for an existing intent.

The file format for import is CSV with no column heading and a single column. For example:

"I want a pony"
"I need a pony"
"I must have a pony"

When importing training phrases, you can choose one of the following import modes:

• Import as new training phrases: The phrases in the files are added to the list of existing phrases.
• Replace existing training phrases: The existing training phrases are deleted, and the training phrases from the files are added.

By default, imported training phrases are automatically annotated. You can disable this behavior by selecting Skip auto annotation.

To export training phrases for an intent:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Intents.
6. Select an intent.
7. Scroll down to the Training phrases section.
8. Select the training phrases you want to export.
9. Click Export.

To import training phrases for an intent:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Intents.
6. Select an intent.
7. Scroll down to the Training phrases section.
8. If desired, select skip auto annotation.
9. Click the import button just above the training phrase list.
10. Select a file and import mode.
11. Click Submit.

Head and supplemental intents

When designing agents, it is sometimes useful to think of intents as either head intents or supplemental intents.

Note: The label "head intent" is a system label that you can apply to an intent. This may be useful when filtering analytics data.

A head intent identifies the end-user's primary purpose for interacting with an agent. A supplemental intent identifies an end-user's subsequent questions that are related to the head intent. These subsequent questions may provide additional context for the end-user's needs, or they may be follow-up questions that help the end-user clarify or better understand something.

A head intent is usually one of the first intents matched in a conversation, and further end-user questions match supplemental intents. For example:

Dialogue	Explanation
End-user: Activate new phone Agent: Sure I can help you with that. What are the last 4 digits of the phone number you want to activate?	Head intent is matched
End-user: 1234 Agent: Are you ready to activate your phone now?	A parameter is set
End-user: Will all of my messages carry over to my new phone? Agent: ...	Supplemental intent is matched

Note: A route group is an easy way to batch add related supplemental intents to multiple pages.