Skip to content

Commit a6b2dac

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
docs: more detailed docs on APIs such as Environment, Intents, Sessions.
PiperOrigin-RevId: 323086730
1 parent 599ede9 commit a6b2dac

8 files changed

Lines changed: 96 additions & 118 deletions

File tree

‎google/cloud/dialogflow/v2/BUILD.bazel‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,13 @@
11
# This file was automatically generated by BuildFileGenerator
2+
# https://github.com/googleapis/gapic-generator/tree/master/rules_gapic/bazel
3+
4+
# Most of the manual changes to this file will be overwritten.
5+
# It's **only** allowed to change the following rule attribute values:
6+
# - names of *_gapic_assembly_* rules
7+
# - certain parameters of *_gapic_library rules, including but not limited to:
8+
# * extra_protoc_parameters
9+
# * extra_protoc_file_parameters
10+
# The complete list of preserved parameters can be found in the source code.
211

312
# This is an API workspace, having public visibility by default makes perfect sense.
413
package(default_visibility = ["//visibility:public"])

‎google/cloud/dialogflow/v2/agent.proto‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -173,8 +173,7 @@ service Agents {
173173
// conversations required for your system.
174174
//
175175
// For more information about agents, see the
176-
// [Agents
177-
// documentation](https://cloud.google.com/dialogflow/docs/agents-overview).
176+
// [Agent guide](https://cloud.google.com/dialogflow/docs/agents-overview).
178177
message Agent {
179178
option (google.api.resource) = {
180179
type: "dialogflow.googleapis.com/Agent"

‎google/cloud/dialogflow/v2/context.proto‎

Lines changed: 16 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -32,24 +32,7 @@ option java_outer_classname = "ContextProto";
3232
option java_package = "com.google.cloud.dialogflow.v2";
3333
option objc_class_prefix = "DF";
3434

35-
// A context represents additional information included with user input or with
36-
// an intent returned by the Dialogflow API. Contexts are helpful for
37-
// differentiating user input which may be vague or have a different meaning
38-
// depending on additional details from your application such as user setting
39-
// and preferences, previous user input, where the user is in your application,
40-
// geographic location, and so on.
41-
//
42-
// You can include contexts as input parameters of a
43-
// [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or
44-
// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) request,
45-
// or as output contexts included in the returned intent.
46-
// Contexts expire when an intent is matched, after the number of `DetectIntent`
47-
// requests specified by the `lifespan_count` parameter, or after 20 minutes
48-
// if no intents are matched for a `DetectIntent` request.
49-
//
50-
// For more information about contexts, see the
51-
// [Dialogflow
52-
// documentation](https://cloud.google.com/dialogflow/docs/contexts-overview).
35+
// Service for managing [Contexts][google.cloud.dialogflow.v2.Context].
5336
service Contexts {
5437
option (google.api.default_host) = "dialogflow.googleapis.com";
5538
option (google.api.oauth_scopes) =
@@ -129,7 +112,21 @@ service Contexts {
129112
}
130113
}
131114

132-
// Represents a context.
115+
// Dialogflow contexts are similar to natural language context. If a person says
116+
// to you "they are orange", you need context in order to understand what "they"
117+
// is referring to. Similarly, for Dialogflow to handle an end-user expression
118+
// like that, it needs to be provided with context in order to correctly match
119+
// an intent.
120+
//
121+
// Using contexts, you can control the flow of a conversation. You can configure
122+
// contexts for an intent by setting input and output contexts, which are
123+
// identified by string names. When an intent is matched, any configured output
124+
// contexts for that intent become active. While any contexts are active,
125+
// Dialogflow is more likely to match intents that are configured with input
126+
// contexts that correspond to the currently active contexts.
127+
//
128+
// For more information about context, see the
129+
// [Contexts guide](https://cloud.google.com/dialogflow/docs/contexts-overview).
133130
message Context {
134131
option (google.api.resource) = {
135132
type: "dialogflow.googleapis.com/Context"

‎google/cloud/dialogflow/v2/entity_type.proto‎

Lines changed: 13 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -32,34 +32,7 @@ option java_outer_classname = "EntityTypeProto";
3232
option java_package = "com.google.cloud.dialogflow.v2";
3333
option objc_class_prefix = "DF";
3434

35-
// Entities are extracted from user input and represent parameters that are
36-
// meaningful to your application. For example, a date range, a proper name
37-
// such as a geographic location or landmark, and so on. Entities represent
38-
// actionable data for your application.
39-
//
40-
// When you define an entity, you can also include synonyms that all map to
41-
// that entity. For example, "soft drink", "soda", "pop", and so on.
42-
//
43-
// There are three types of entities:
44-
//
45-
// * **System** - entities that are defined by the Dialogflow API for common
46-
// data types such as date, time, currency, and so on. A system entity is
47-
// represented by the `EntityType` type.
48-
//
49-
// * **Custom** - entities that are defined by you that represent
50-
// actionable data that is meaningful to your application. For example,
51-
// you could define a `pizza.sauce` entity for red or white pizza sauce,
52-
// a `pizza.cheese` entity for the different types of cheese on a pizza,
53-
// a `pizza.topping` entity for different toppings, and so on. A custom
54-
// entity is represented by the `EntityType` type.
55-
//
56-
// * **User** - entities that are built for an individual user such as
57-
// favorites, preferences, playlists, and so on. A user entity is
58-
// represented by the [SessionEntityType][google.cloud.dialogflow.v2.SessionEntityType] type.
59-
//
60-
// For more information about entity types, see the
61-
// [Dialogflow
62-
// documentation](https://cloud.google.com/dialogflow/docs/entities-overview).
35+
// Service for managing [EntityTypes][google.cloud.dialogflow.v2.EntityType].
6336
service EntityTypes {
6437
option (google.api.default_host) = "dialogflow.googleapis.com";
6538
option (google.api.oauth_scopes) =
@@ -194,9 +167,18 @@ service EntityTypes {
194167
}
195168
}
196169

197-
// Represents an entity type.
198-
// Entity types serve as a tool for extracting parameter values from natural
199-
// language queries.
170+
// Each intent parameter has a type, called the entity type, which dictates
171+
// exactly how data from an end-user expression is extracted.
172+
//
173+
// Dialogflow provides predefined system entities that can match many common
174+
// types of data. For example, there are system entities for matching dates,
175+
// times, colors, email addresses, and so on. You can also create your own
176+
// custom entities for matching custom data. For example, you could define a
177+
// vegetable entity that can match the types of vegetables available for
178+
// purchase with a grocery store agent.
179+
//
180+
// For more information, see the
181+
// [Entity guide](https://cloud.google.com/dialogflow/docs/entities-overview).
200182
message EntityType {
201183
option (google.api.resource) = {
202184
type: "dialogflow.googleapis.com/EntityType"

‎google/cloud/dialogflow/v2/environment.proto‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ option java_outer_classname = "EnvironmentProto";
3232
option java_package = "com.google.cloud.dialogflow.v2";
3333
option objc_class_prefix = "DF";
3434

35-
// Manages agent environments.
35+
// Service for managing [Environments][google.cloud.dialogflow.v2.Environment].
3636
service Environments {
3737
option (google.api.default_host) = "dialogflow.googleapis.com";
3838
option (google.api.oauth_scopes) =
@@ -47,7 +47,24 @@ service Environments {
4747
}
4848
}
4949

50-
// Represents an agent environment.
50+
// You can create multiple versions of your agent and publish them to separate
51+
// environments.
52+
//
53+
// When you edit an agent, you are editing the draft agent. At any point, you
54+
// can save the draft agent as an agent version, which is an immutable snapshot
55+
// of your agent.
56+
//
57+
// When you save the draft agent, it is published to the default environment.
58+
// When you create agent versions, you can publish them to custom environments.
59+
// You can create a variety of custom environments for:
60+
//
61+
// - testing
62+
// - development
63+
// - production
64+
// - etc.
65+
//
66+
// For more information, see the [versions and environments
67+
// guide](https://cloud.google.com/dialogflow/docs/agents-versions).
5168
message Environment {
5269
option (google.api.resource) = {
5370
type: "dialogflow.googleapis.com/Environment"

‎google/cloud/dialogflow/v2/intent.proto‎

Lines changed: 10 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -36,38 +36,7 @@ option java_outer_classname = "IntentProto";
3636
option java_package = "com.google.cloud.dialogflow.v2";
3737
option objc_class_prefix = "DF";
3838

39-
// An intent represents a mapping between input from a user and an action to
40-
// be taken by your application. When you pass user input to the
41-
// [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or
42-
// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) method, the
43-
// Dialogflow API analyzes the input and searches
44-
// for a matching intent. If no match is found, the Dialogflow API returns a
45-
// fallback intent (`is_fallback` = true).
46-
//
47-
// You can provide additional information for the Dialogflow API to use to
48-
// match user input to an intent by adding the following to your intent.
49-
//
50-
// * **Contexts** - provide additional context for intent analysis. For
51-
// example, if an intent is related to an object in your application that
52-
// plays music, you can provide a context to determine when to match the
53-
// intent if the user input is "turn it off". You can include a context
54-
// that matches the intent when there is previous user input of
55-
// "play music", and not when there is previous user input of
56-
// "turn on the light".
57-
//
58-
// * **Events** - allow for matching an intent by using an event name
59-
// instead of user input. Your application can provide an event name and
60-
// related parameters to the Dialogflow API to match an intent. For
61-
// example, when your application starts, you can send a welcome event
62-
// with a user name parameter to the Dialogflow API to match an intent with
63-
// a personalized welcome message for the user.
64-
//
65-
// * **Training phrases** - provide examples of user input to train the
66-
// Dialogflow API agent to better match intents.
67-
//
68-
// For more information about intents, see the
69-
// [Dialogflow
70-
// documentation](https://cloud.google.com/dialogflow/docs/intents-overview).
39+
// Service for managing [Intents][google.cloud.dialogflow.v2.Intent].
7140
service Intents {
7241
option (google.api.default_host) = "dialogflow.googleapis.com";
7342
option (google.api.oauth_scopes) =
@@ -152,9 +121,15 @@ service Intents {
152121
}
153122
}
154123

155-
// Represents an intent.
156-
// Intents convert a number of user expressions or patterns into an action. An
157-
// action is an extraction of a user command or sentence semantics.
124+
// An intent categorizes an end-user's intention for one conversation turn. For
125+
// each agent, you define many intents, where your combined intents can handle a
126+
// complete conversation. When an end-user writes or says something, referred to
127+
// as an end-user expression or end-user input, Dialogflow matches the end-user
128+
// input to the best intent in your agent. Matching an intent is also known as
129+
// intent classification.
130+
//
131+
// For more information, see the [intent
132+
// guide](https://cloud.google.com/dialogflow/docs/intents-overview).
158133
message Intent {
159134
option (google.api.resource) = {
160135
type: "dialogflow.googleapis.com/Intent"

‎google/cloud/dialogflow/v2/session.proto‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -43,10 +43,10 @@ option (google.api.resource_definition) = {
4343
pattern: "projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session}"
4444
};
4545

46-
// A session represents an interaction with a user. You retrieve user input
47-
// and pass it to the [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or
48-
// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) method to determine
49-
// user intent and respond.
46+
// A service used for session interactions.
47+
//
48+
// For more information, see the [API interactions
49+
// guide](https://cloud.google.com/dialogflow/docs/api-overview).
5050
service Sessions {
5151
option (google.api.default_host) = "dialogflow.googleapis.com";
5252
option (google.api.oauth_scopes) =
@@ -87,6 +87,9 @@ message DetectIntentRequest {
8787
// `User Id`. They can be a random number or some type of user and session
8888
// identifiers (preferably hashed). The length of the `Session ID` and
8989
// `User ID` must not exceed 36 characters.
90+
//
91+
// For more information, see the [API interactions
92+
// guide](https://cloud.google.com/dialogflow/docs/api-overview).
9093
string session = 1 [
9194
(google.api.field_behavior) = REQUIRED,
9295
(google.api.resource_reference) = {
@@ -362,6 +365,9 @@ message StreamingDetectIntentRequest {
362365
// `User Id`. They can be a random number or some type of user and session
363366
// identifiers (preferably hashed). The length of the `Session ID` and
364367
// `User ID` must not exceed 36 characters.
368+
//
369+
// For more information, see the [API interactions
370+
// guide](https://cloud.google.com/dialogflow/docs/api-overview).
365371
string session = 1 [
366372
(google.api.field_behavior) = REQUIRED,
367373
(google.api.resource_reference) = {
@@ -591,8 +597,16 @@ message SentimentAnalysisRequestConfig {
591597
bool analyze_query_text_sentiment = 1;
592598
}
593599

594-
// The result of sentiment analysis as configured by
595-
// `sentiment_analysis_request_config`.
600+
// The result of sentiment analysis. Sentiment analysis inspects user input
601+
// and identifies the prevailing subjective opinion, especially to determine a
602+
// user's attitude as positive, negative, or neutral.
603+
// For [Participants.AnalyzeContent][google.cloud.dialogflow.v2.Participants.AnalyzeContent], it needs to be configured in
604+
// [DetectIntentRequest.query_params][google.cloud.dialogflow.v2.DetectIntentRequest.query_params]. For
605+
// [Participants.StreamingAnalyzeContent][google.cloud.dialogflow.v2.Participants.StreamingAnalyzeContent], it needs to be configured in
606+
// [StreamingDetectIntentRequest.query_params][google.cloud.dialogflow.v2.StreamingDetectIntentRequest.query_params].
607+
// And for [Participants.AnalyzeContent][google.cloud.dialogflow.v2.Participants.AnalyzeContent] and
608+
// [Participants.StreamingAnalyzeContent][google.cloud.dialogflow.v2.Participants.StreamingAnalyzeContent], it needs to be configured in
609+
// [ConversationProfile.human_agent_assistant_config][google.cloud.dialogflow.v2.ConversationProfile.human_agent_assistant_config]
596610
message SentimentAnalysisResult {
597611
// The sentiment analysis result for `query_text`.
598612
Sentiment query_text_sentiment = 1;

‎google/cloud/dialogflow/v2/session_entity_type.proto‎

Lines changed: 8 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -32,23 +32,7 @@ option java_outer_classname = "SessionEntityTypeProto";
3232
option java_package = "com.google.cloud.dialogflow.v2";
3333
option objc_class_prefix = "DF";
3434

35-
// Entities are extracted from user input and represent parameters that are
36-
// meaningful to your application. For example, a date range, a proper name
37-
// such as a geographic location or landmark, and so on. Entities represent
38-
// actionable data for your application.
39-
//
40-
// Session entity types are referred to as **User** entity types and are
41-
// entities that are built for an individual user such as
42-
// favorites, preferences, playlists, and so on. You can redefine a session
43-
// entity type at the session level.
44-
//
45-
// Session entity methods do not work with Google Assistant integration.
46-
// Contact Dialogflow support if you need to use session entities
47-
// with Google Assistant integration.
48-
//
49-
// For more information about entity types, see the
50-
// [Dialogflow
51-
// documentation](https://cloud.google.com/dialogflow/docs/entities-overview).
35+
// Service for managing [SessionEntityTypes][google.cloud.dialogflow.v2.SessionEntityType].
5236
service SessionEntityTypes {
5337
option (google.api.default_host) = "dialogflow.googleapis.com";
5438
option (google.api.oauth_scopes) =
@@ -139,13 +123,14 @@ service SessionEntityTypes {
139123
}
140124
}
141125

142-
// Represents a session entity type.
143-
//
144-
// Extends or replaces a custom entity type at the user session level (we
145-
// refer to the entity types defined at the agent level as "custom entity
146-
// types").
126+
// A session represents a conversation between a Dialogflow agent and an
127+
// end-user. You can create special entities, called session entities, during a
128+
// session. Session entities can extend or replace custom entity types and only
129+
// exist during the session that they were created for. All session data,
130+
// including session entities, is stored by Dialogflow for 20 minutes.
147131
//
148-
// Note: session entity types apply to all queries, regardless of the language.
132+
// For more information, see the [session entity
133+
// guide](https://cloud.google.com/dialogflow/docs/entities-session).
149134
message SessionEntityType {
150135
option (google.api.resource) = {
151136
type: "dialogflow.googleapis.com/SessionEntityType"

0 commit comments

Comments
 (0)