1// Copyright 2023 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.cloud.dialogflow.cx.v3;
18
19import "google/api/resource.proto";
20import "google/cloud/dialogflow/cx/v3/response_message.proto";
21import "google/protobuf/struct.proto";
22
23option cc_enable_arenas = true;
24option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3";
25option go_package = "cloud.google.com/go/dialogflow/cx/apiv3/cxpb;cxpb";
26option java_multiple_files = true;
27option java_outer_classname = "FulfillmentProto";
28option java_package = "com.google.cloud.dialogflow.cx.v3";
29option objc_class_prefix = "DF";
30option ruby_package = "Google::Cloud::Dialogflow::CX::V3";
31
32// A fulfillment can do one or more of the following actions at the same time:
33//
34//   * Generate rich message responses.
35//   * Set parameter values.
36//   * Call the webhook.
37//
38// Fulfillments can be called at various stages in the
39// [Page][google.cloud.dialogflow.cx.v3.Page] or
40// [Form][google.cloud.dialogflow.cx.v3.Form] lifecycle. For example, when a
41// [DetectIntentRequest][google.cloud.dialogflow.cx.v3.DetectIntentRequest]
42// drives a session to enter a new page, the page's entry fulfillment can add a
43// static response to the
44// [QueryResult][google.cloud.dialogflow.cx.v3.QueryResult] in the returning
45// [DetectIntentResponse][google.cloud.dialogflow.cx.v3.DetectIntentResponse],
46// call the webhook (for example, to load user data from a database), or both.
47message Fulfillment {
48  // Setting a parameter value.
49  message SetParameterAction {
50    // Display name of the parameter.
51    string parameter = 1;
52
53    // The new value of the parameter. A null value clears the parameter.
54    google.protobuf.Value value = 2;
55  }
56
57  // A list of cascading if-else conditions. Cases are mutually exclusive.
58  // The first one with a matching condition is selected, all the rest ignored.
59  message ConditionalCases {
60    // Each case has a Boolean condition. When it is evaluated to be True, the
61    // corresponding messages will be selected and evaluated recursively.
62    message Case {
63      // The list of messages or conditional cases to activate for this case.
64      message CaseContent {
65        // Either a message is returned or additional cases to be evaluated.
66        oneof cases_or_message {
67          // Returned message.
68          ResponseMessage message = 1;
69
70          // Additional cases to be evaluated.
71          ConditionalCases additional_cases = 2;
72        }
73      }
74
75      // The condition to activate and select this case. Empty means the
76      // condition is always true. The condition is evaluated against [form
77      // parameters][Form.parameters] or [session
78      // parameters][SessionInfo.parameters].
79      //
80      // See the [conditions
81      // reference](https://cloud.google.com/dialogflow/cx/docs/reference/condition).
82      string condition = 1;
83
84      // A list of case content.
85      repeated CaseContent case_content = 2;
86    }
87
88    // A list of cascading if-else conditions.
89    repeated Case cases = 1;
90  }
91
92  // The list of rich message responses to present to the user.
93  repeated ResponseMessage messages = 1;
94
95  // The webhook to call.
96  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
97  // ID>/webhooks/<Webhook ID>`.
98  string webhook = 2 [(google.api.resource_reference) = {
99    type: "dialogflow.googleapis.com/Webhook"
100  }];
101
102  // Whether Dialogflow should return currently queued fulfillment response
103  // messages in streaming APIs. If a webhook is specified, it happens before
104  // Dialogflow invokes webhook.
105  // Warning:
106  // 1) This flag only affects streaming API. Responses are still queued
107  // and returned once in non-streaming API.
108  // 2) The flag can be enabled in any fulfillment but only the first 3 partial
109  // responses will be returned. You may only want to apply it to fulfillments
110  // that have slow webhooks.
111  bool return_partial_responses = 8;
112
113  // The value of this field will be populated in the
114  // [WebhookRequest][google.cloud.dialogflow.cx.v3.WebhookRequest]
115  // `fulfillmentInfo.tag` field by Dialogflow when the associated webhook is
116  // called.
117  // The tag is typically used by the webhook service to identify which
118  // fulfillment is being called, but it could be used for other purposes.
119  // This field is required if `webhook` is specified.
120  string tag = 3;
121
122  // Set parameter values before executing the webhook.
123  repeated SetParameterAction set_parameter_actions = 4;
124
125  // Conditional cases for this fulfillment.
126  repeated ConditionalCases conditional_cases = 5;
127}
128