docs: added explanation for SuggestionResult (#937)

* feat: added HUMAN_INTERVENTION_NEEDED type in ConversationEvent feat: added SetSuggestionFeatureConfig and ClearSuggestionFeatureConfig apis feat: added AGENT_FACING_SMART_REPLY type in KnowledgeType feat: added GcsDestination. docs: added explanation for uri fields in resources docs: added explanation for SuggestionResult docs: added explanation for language code in session PiperOrigin-RevId: 435479473 Source-Link: googleapis/googleapis@d9ca515 Source-Link: googleapis/googleapis-gen@358c4b9 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMzU4YzRiOWIxZGYxNDliYzUwNjIwYmMzODExMDA0ZjkxM2Q0MzIzNiJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * docs: added explanation for SuggestionResult PiperOrigin-RevId: 435670355 Source-Link: googleapis/googleapis@5d85995 Source-Link: googleapis/googleapis-gen@1b913e4 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMWI5MTNlNDQ4NGE2NmIzZjRkMDFjNTViZTE3NDcwNDI3MjQ2NjI2NCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
googleapis · Mar 18, 2022 · c14c11c · c14c11c
1 parent 32cec0c
commit c14c11c
Show file tree

Hide file tree

Showing 36 changed files with 63,372 additions and 59,432 deletions.
diff --git a/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2/participant.proto b/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2/participant.proto
@@ -396,11 +396,21 @@ message AnalyzeContentResponse {
   // The suggestions for most recent human agent. The order is the same as
   // [HumanAgentAssistantConfig.SuggestionConfig.feature_configs][google.cloud.dialogflow.v2.HumanAgentAssistantConfig.SuggestionConfig.feature_configs] of
   // [HumanAgentAssistantConfig.human_agent_suggestion_config][google.cloud.dialogflow.v2.HumanAgentAssistantConfig.human_agent_suggestion_config].
+  //
+  // Note that any failure of Agent Assist features will not lead to the overall
+  // failure of an AnalyzeContent API call. Instead, the features will
+  // fail silently with the error field set in the corresponding
+  // SuggestionResult.
   repeated SuggestionResult human_agent_suggestion_results = 6;
 
   // The suggestions for end user. The order is the same as
   // [HumanAgentAssistantConfig.SuggestionConfig.feature_configs][google.cloud.dialogflow.v2.HumanAgentAssistantConfig.SuggestionConfig.feature_configs] of
   // [HumanAgentAssistantConfig.end_user_suggestion_config][google.cloud.dialogflow.v2.HumanAgentAssistantConfig.end_user_suggestion_config].
+  //
+  // Same as human_agent_suggestion_results, any failure of Agent Assist
+  // features will not lead to the overall failure of an AnalyzeContent API
+  // call. Instead, the features will fail silently with the error field set in
+  // the corresponding SuggestionResult.
   repeated SuggestionResult end_user_suggestion_results = 7;
 
   // Indicates the parameters of DTMF.

diff --git a/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/agent.proto b/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/agent.proto
@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -20,7 +20,6 @@ import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
-import "google/cloud/dialogflow/v2beta1/environment.proto";
 import "google/cloud/dialogflow/v2beta1/validation_result.proto";
 import "google/longrunning/operations.proto";
 import "google/protobuf/empty.proto";
@@ -478,6 +477,12 @@ message ExportAgentRequest {
   // URI to export the agent to.
   // The format of this URI must be `gs://<bucket-name>/<object-name>`.
   // If left unspecified, the serialized agent is returned inline.
+  //
+  // Dialogflow performs a write operation for the Cloud Storage object
+  // on the caller's behalf, so your request authentication must
+  // have write permissions for the object. For more information, see
+  // [Dialogflow access
+  // control](https://cloud.google.com/dialogflow/cx/docs/concept/access-control#storage).
   string agent_uri = 2;
 }
 
@@ -510,6 +515,12 @@ message ImportAgentRequest {
   oneof agent {
     // The URI to a Google Cloud Storage file containing the agent to import.
     // Note: The URI must start with "gs://".
+    //
+    // Dialogflow performs a read operation for the Cloud Storage object
+    // on the caller's behalf, so your request authentication must
+    // have read permissions for the object. For more information, see
+    // [Dialogflow access
+    // control](https://cloud.google.com/dialogflow/cx/docs/concept/access-control#storage).
     string agent_uri = 2;
 
     // Zip compressed raw byte content for agent.
@@ -533,6 +544,12 @@ message RestoreAgentRequest {
   oneof agent {
     // The URI to a Google Cloud Storage file containing the agent to restore.
     // Note: The URI must start with "gs://".
+    //
+    // Dialogflow performs a read operation for the Cloud Storage object
+    // on the caller's behalf, so your request authentication must
+    // have read permissions for the object. For more information, see
+    // [Dialogflow access
+    // control](https://cloud.google.com/dialogflow/cx/docs/concept/access-control#storage).
     string agent_uri = 2;
 
     // Zip compressed raw byte content for agent.

diff --git a/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/answer_record.proto b/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/answer_record.proto
@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -21,7 +21,6 @@ import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/cloud/dialogflow/v2beta1/participant.proto";
-import "google/protobuf/empty.proto";
 import "google/protobuf/field_mask.proto";
 import "google/protobuf/timestamp.proto";
 

diff --git a/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/audio_config.proto b/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/audio_config.proto
@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -16,12 +16,9 @@ syntax = "proto3";
 
 package google.cloud.dialogflow.v2beta1;
 
-import "google/api/annotations.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/protobuf/duration.proto";
-import "google/protobuf/field_mask.proto";
-import "google/protobuf/timestamp.proto";
 
 option cc_enable_arenas = true;
 option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1";

diff --git a/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/context.proto b/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/context.proto
@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

diff --git a/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/conversation.proto b/packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/conversation.proto
@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -20,16 +20,8 @@ import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
-import "google/cloud/dialogflow/v2beta1/audio_config.proto";
-import "google/cloud/dialogflow/v2beta1/conversation_profile.proto";
-import "google/cloud/dialogflow/v2beta1/gcs.proto";
 import "google/cloud/dialogflow/v2beta1/participant.proto";
-import "google/cloud/dialogflow/v2beta1/session.proto";
-import "google/longrunning/operations.proto";
-import "google/protobuf/empty.proto";
-import "google/protobuf/field_mask.proto";
 import "google/protobuf/timestamp.proto";
-import "google/rpc/status.proto";
 
 option cc_enable_arenas = true;
 option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1";

diff --git a/...s/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/conversation_event.proto b/...s/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/conversation_event.proto
@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -16,7 +16,6 @@ syntax = "proto3";
 
 package google.cloud.dialogflow.v2beta1;
 
-import "google/api/annotations.proto";
 import "google/cloud/dialogflow/v2beta1/participant.proto";
 import "google/rpc/status.proto";
 
@@ -44,6 +43,10 @@ message ConversationEvent {
     // is terminated, or a conversation is closed via the API.
     CONVERSATION_FINISHED = 2;
 
+    // An existing conversation has received notification from Dialogflow that
+    // human intervention is required.
+    HUMAN_INTERVENTION_NEEDED = 3;
+
     // An existing conversation has received a new message, either from API or
     // telephony. It is configured in
     // [ConversationProfile.new_message_event_notification_config][google.cloud.dialogflow.v2beta1.ConversationProfile.new_message_event_notification_config]

diff --git a/...google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/conversation_profile.proto b/...google-cloud-dialogflow/protos/google/cloud/dialogflow/v2beta1/conversation_profile.proto
@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -21,10 +21,8 @@ import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/cloud/dialogflow/v2beta1/audio_config.proto";
-import "google/cloud/dialogflow/v2beta1/document.proto";
 import "google/cloud/dialogflow/v2beta1/participant.proto";
 import "google/longrunning/operations.proto";
-import "google/protobuf/duration.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/field_mask.proto";
 import "google/protobuf/timestamp.proto";
@@ -118,6 +116,63 @@ service ConversationProfiles {
     };
     option (google.api.method_signature) = "name";
   }
+
+  // Adds or updates a suggestion feature in a conversation profile.
+  // If the conversation profile contains the type of suggestion feature for
+  // the participant role, it will update it. Otherwise it will insert the
+  // suggestion feature.
+  //
+  // This method is a [long-running
+  // operation](https://cloud.google.com/dialogflow/es/docs/how/long-running-operations).
+  // The returned `Operation` type has the following method-specific fields:
+  //
+  // - `metadata`: [SetSuggestionFeatureConfigOperationMetadata][google.cloud.dialogflow.v2beta1.SetSuggestionFeatureConfigOperationMetadata]
+  // - `response`: [ConversationProfile][google.cloud.dialogflow.v2beta1.ConversationProfile]
+  //
+  // If a long running operation to add or update suggestion feature
+  // config for the same conversation profile, participant role and suggestion
+  // feature type exists, please cancel the existing long running operation
+  // before sending such request, otherwise the request will be rejected.
+  rpc SetSuggestionFeatureConfig(SetSuggestionFeatureConfigRequest) returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v2beta1/{conversation_profile=projects/*/conversationProfiles/*}:setSuggestionFeatureConfig"
+      body: "*"
+      additional_bindings {
+        post: "/v2beta1/{conversation_profile=projects/*/locations/*/conversationProfiles/*}:setSuggestionFeatureConfig"
+        body: "*"
+      }
+    };
+    option (google.api.method_signature) = "conversation_profile";
+    option (google.longrunning.operation_info) = {
+      response_type: "ConversationProfile"
+      metadata_type: "SetSuggestionFeatureConfigOperationMetadata"
+    };
+  }
+
+  // Clears a suggestion feature from a conversation profile for the given
+  // participant role.
+  //
+  // This method is a [long-running
+  // operation](https://cloud.google.com/dialogflow/es/docs/how/long-running-operations).
+  // The returned `Operation` type has the following method-specific fields:
+  //
+  // - `metadata`: [ClearSuggestionFeatureConfigOperationMetadata][google.cloud.dialogflow.v2beta1.ClearSuggestionFeatureConfigOperationMetadata]
+  // - `response`: [ConversationProfile][google.cloud.dialogflow.v2beta1.ConversationProfile]
+  rpc ClearSuggestionFeatureConfig(ClearSuggestionFeatureConfigRequest) returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v2beta1/{conversation_profile=projects/*/conversationProfiles/*}:clearSuggestionFeatureConfig"
+      body: "*"
+      additional_bindings {
+        post: "/v2beta1/{conversation_profile=projects/*/locations/*/conversationProfiles/*}:clearSuggestionFeatureConfig"
+        body: "*"
+      }
+    };
+    option (google.api.method_signature) = "conversation_profile";
+    option (google.longrunning.operation_info) = {
+      response_type: "ConversationProfile"
+      metadata_type: "ClearSuggestionFeatureConfigOperationMetadata"
+    };
+  }
 }
 
 // Defines the services to connect to incoming Dialogflow conversations.
@@ -501,11 +556,15 @@ message NotificationConfig {
   // [CONVERSATION_STARTED][google.cloud.dialogflow.v2beta1.ConversationEvent.Type.CONVERSATION_STARTED] as
   // serialized [ConversationEvent][google.cloud.dialogflow.v2beta1.ConversationEvent] protos.
   //
-  // Notification works for phone calls, if this topic either is in the same
-  // project as the conversation or you grant `service-<Conversation Project
+  // For telephony integration to receive notification, make sure either this
+  // topic is in the same project as the conversation or you grant
+  // `service-<Conversation Project
   // Number>@gcp-sa-dialogflow.iam.gserviceaccount.com` the `Dialogflow Service
   // Agent` role in the topic project.
   //
+  // For chat integration to receive notification, make sure API caller has been
+  // granted the `Dialogflow Service Agent` role for the topic.
+  //
   // Format: `projects/<Project ID>/locations/<Location ID>/topics/<Topic ID>`.
   string topic = 1;
 
@@ -604,3 +663,72 @@ message DeleteConversationProfileRequest {
     }
   ];
 }
+
+// The request message for
+// [ConversationProfiles.SetSuggestionFeature][].
+message SetSuggestionFeatureConfigRequest {
+  // Required. The Conversation Profile to add or update the suggestion feature
+  // config. Format: `projects/<Project ID>/locations/<Location
+  // ID>/conversationProfiles/<Conversation Profile ID>`.
+  string conversation_profile = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The participant role to add or update the suggestion feature
+  // config. Only HUMAN_AGENT or END_USER can be used.
+  Participant.Role participant_role = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The suggestion feature config to add or update.
+  HumanAgentAssistantConfig.SuggestionFeatureConfig suggestion_feature_config = 3 [(google.api.field_behavior) = REQUIRED];
+}
+
+// The request message for [ConversationProfiles.ClearFeature][].
+message ClearSuggestionFeatureConfigRequest {
+  // Required. The Conversation Profile to add or update the suggestion feature
+  // config. Format: `projects/<Project ID>/locations/<Location
+  // ID>/conversationProfiles/<Conversation Profile ID>`.
+  string conversation_profile = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The participant role to remove the suggestion feature
+  // config. Only HUMAN_AGENT or END_USER can be used.
+  Participant.Role participant_role = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The type of the suggestion feature to remove.
+  SuggestionFeature.Type suggestion_feature_type = 3 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Metadata for a [ConversationProfile.SetSuggestionFeatureConfig][]
+// operation.
+message SetSuggestionFeatureConfigOperationMetadata {
+  // The resource name of the conversation profile. Format:
+  // `projects/<Project ID>/locations/<Location
+  // ID>/conversationProfiles/<Conversation Profile ID>`
+  string conversation_profile = 1;
+
+  // Required. The participant role to add or update the suggestion feature
+  // config. Only HUMAN_AGENT or END_USER can be used.
+  Participant.Role participant_role = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The type of the suggestion feature to add or update.
+  SuggestionFeature.Type suggestion_feature_type = 3 [(google.api.field_behavior) = REQUIRED];
+
+  // Timestamp whe the request was created. The time is measured on server side.
+  google.protobuf.Timestamp create_time = 4;
+}
+
+// Metadata for a [ConversationProfile.ClearSuggestionFeatureConfig][]
+// operation.
+message ClearSuggestionFeatureConfigOperationMetadata {
+  // The resource name of the conversation profile. Format:
+  // `projects/<Project ID>/locations/<Location
+  // ID>/conversationProfiles/<Conversation Profile ID>`
+  string conversation_profile = 1;
+
+  // Required. The participant role to remove the suggestion feature
+  // config. Only HUMAN_AGENT or END_USER can be used.
+  Participant.Role participant_role = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The type of the suggestion feature to remove.
+  SuggestionFeature.Type suggestion_feature_type = 3 [(google.api.field_behavior) = REQUIRED];
+
+  // Timestamp whe the request was created. The time is measured on server side.
+  google.protobuf.Timestamp create_time = 4;
+}