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.v2; 18 19import "google/api/annotations.proto"; 20import "google/api/client.proto"; 21import "google/api/field_behavior.proto"; 22import "google/api/resource.proto"; 23import "google/protobuf/empty.proto"; 24import "google/protobuf/field_mask.proto"; 25import "google/protobuf/struct.proto"; 26 27option cc_enable_arenas = true; 28option csharp_namespace = "Google.Cloud.Dialogflow.V2"; 29option go_package = "cloud.google.com/go/dialogflow/apiv2/dialogflowpb;dialogflowpb"; 30option java_multiple_files = true; 31option java_outer_classname = "ContextProto"; 32option java_package = "com.google.cloud.dialogflow.v2"; 33option objc_class_prefix = "DF"; 34 35// Service for managing [Contexts][google.cloud.dialogflow.v2.Context]. 36service Contexts { 37 option (google.api.default_host) = "dialogflow.googleapis.com"; 38 option (google.api.oauth_scopes) = 39 "https://www.googleapis.com/auth/cloud-platform," 40 "https://www.googleapis.com/auth/dialogflow"; 41 42 // Returns the list of all contexts in the specified session. 43 rpc ListContexts(ListContextsRequest) returns (ListContextsResponse) { 44 option (google.api.http) = { 45 get: "/v2/{parent=projects/*/agent/sessions/*}/contexts" 46 additional_bindings { 47 get: "/v2/{parent=projects/*/agent/environments/*/users/*/sessions/*}/contexts" 48 } 49 additional_bindings { 50 get: "/v2/{parent=projects/*/locations/*/agent/sessions/*}/contexts" 51 } 52 additional_bindings { 53 get: "/v2/{parent=projects/*/locations/*/agent/environments/*/users/*/sessions/*}/contexts" 54 } 55 }; 56 option (google.api.method_signature) = "parent"; 57 } 58 59 // Retrieves the specified context. 60 rpc GetContext(GetContextRequest) returns (Context) { 61 option (google.api.http) = { 62 get: "/v2/{name=projects/*/agent/sessions/*/contexts/*}" 63 additional_bindings { 64 get: "/v2/{name=projects/*/agent/environments/*/users/*/sessions/*/contexts/*}" 65 } 66 additional_bindings { 67 get: "/v2/{name=projects/*/locations/*/agent/sessions/*/contexts/*}" 68 } 69 additional_bindings { 70 get: "/v2/{name=projects/*/locations/*/agent/environments/*/users/*/sessions/*/contexts/*}" 71 } 72 }; 73 option (google.api.method_signature) = "name"; 74 } 75 76 // Creates a context. 77 // 78 // If the specified context already exists, overrides the context. 79 rpc CreateContext(CreateContextRequest) returns (Context) { 80 option (google.api.http) = { 81 post: "/v2/{parent=projects/*/agent/sessions/*}/contexts" 82 body: "context" 83 additional_bindings { 84 post: "/v2/{parent=projects/*/agent/environments/*/users/*/sessions/*}/contexts" 85 body: "context" 86 } 87 additional_bindings { 88 post: "/v2/{parent=projects/*/locations/*/agent/sessions/*}/contexts" 89 body: "context" 90 } 91 additional_bindings { 92 post: "/v2/{parent=projects/*/locations/*/agent/environments/*/users/*/sessions/*}/contexts" 93 body: "context" 94 } 95 }; 96 option (google.api.method_signature) = "parent,context"; 97 } 98 99 // Updates the specified context. 100 rpc UpdateContext(UpdateContextRequest) returns (Context) { 101 option (google.api.http) = { 102 patch: "/v2/{context.name=projects/*/agent/sessions/*/contexts/*}" 103 body: "context" 104 additional_bindings { 105 patch: "/v2/{context.name=projects/*/agent/environments/*/users/*/sessions/*/contexts/*}" 106 body: "context" 107 } 108 additional_bindings { 109 patch: "/v2/{context.name=projects/*/locations/*/agent/sessions/*/contexts/*}" 110 body: "context" 111 } 112 additional_bindings { 113 patch: "/v2/{context.name=projects/*/locations/*/agent/environments/*/users/*/sessions/*/contexts/*}" 114 body: "context" 115 } 116 }; 117 option (google.api.method_signature) = "context,update_mask"; 118 } 119 120 // Deletes the specified context. 121 rpc DeleteContext(DeleteContextRequest) returns (google.protobuf.Empty) { 122 option (google.api.http) = { 123 delete: "/v2/{name=projects/*/agent/sessions/*/contexts/*}" 124 additional_bindings { 125 delete: "/v2/{name=projects/*/agent/environments/*/users/*/sessions/*/contexts/*}" 126 } 127 additional_bindings { 128 delete: "/v2/{name=projects/*/locations/*/agent/sessions/*/contexts/*}" 129 } 130 additional_bindings { 131 delete: "/v2/{name=projects/*/locations/*/agent/environments/*/users/*/sessions/*/contexts/*}" 132 } 133 }; 134 option (google.api.method_signature) = "name"; 135 } 136 137 // Deletes all active contexts in the specified session. 138 rpc DeleteAllContexts(DeleteAllContextsRequest) 139 returns (google.protobuf.Empty) { 140 option (google.api.http) = { 141 delete: "/v2/{parent=projects/*/agent/sessions/*}/contexts" 142 additional_bindings { 143 delete: "/v2/{parent=projects/*/agent/environments/*/users/*/sessions/*}/contexts" 144 } 145 additional_bindings { 146 delete: "/v2/{parent=projects/*/locations/*/agent/sessions/*}/contexts" 147 } 148 additional_bindings { 149 delete: "/v2/{parent=projects/*/locations/*/agent/environments/*/users/*/sessions/*}/contexts" 150 } 151 }; 152 option (google.api.method_signature) = "parent"; 153 } 154} 155 156// Dialogflow contexts are similar to natural language context. If a person says 157// to you "they are orange", you need context in order to understand what "they" 158// is referring to. Similarly, for Dialogflow to handle an end-user expression 159// like that, it needs to be provided with context in order to correctly match 160// an intent. 161// 162// Using contexts, you can control the flow of a conversation. You can configure 163// contexts for an intent by setting input and output contexts, which are 164// identified by string names. When an intent is matched, any configured output 165// contexts for that intent become active. While any contexts are active, 166// Dialogflow is more likely to match intents that are configured with input 167// contexts that correspond to the currently active contexts. 168// 169// For more information about context, see the 170// [Contexts guide](https://cloud.google.com/dialogflow/docs/contexts-overview). 171message Context { 172 option (google.api.resource) = { 173 type: "dialogflow.googleapis.com/Context" 174 pattern: "projects/{project}/agent/sessions/{session}/contexts/{context}" 175 pattern: "projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session}/contexts/{context}" 176 pattern: "projects/{project}/locations/{location}/agent/sessions/{session}/contexts/{context}" 177 pattern: "projects/{project}/locations/{location}/agent/environments/{environment}/users/{user}/sessions/{session}/contexts/{context}" 178 }; 179 180 // Required. The unique identifier of the context. Format: 181 // `projects/<Project ID>/agent/sessions/<Session ID>/contexts/<Context ID>`, 182 // or `projects/<Project ID>/agent/environments/<Environment ID>/users/<User 183 // ID>/sessions/<Session ID>/contexts/<Context ID>`. 184 // 185 // The `Context ID` is always converted to lowercase, may only contain 186 // characters in `a-zA-Z0-9_-%` and may be at most 250 bytes long. 187 // 188 // If `Environment ID` is not specified, we assume default 'draft' 189 // environment. If `User ID` is not specified, we assume default '-' user. 190 // 191 // The following context names are reserved for internal use by Dialogflow. 192 // You should not use these contexts or create contexts with these names: 193 // 194 // * `__system_counters__` 195 // * `*_id_dialog_context` 196 // * `*_dialog_params_size` 197 string name = 1 [(google.api.field_behavior) = REQUIRED]; 198 199 // Optional. The number of conversational query requests after which the 200 // context expires. The default is `0`. If set to `0`, the context expires 201 // immediately. Contexts expire automatically after 20 minutes if there 202 // are no matching queries. 203 int32 lifespan_count = 2 [(google.api.field_behavior) = OPTIONAL]; 204 205 // Optional. The collection of parameters associated with this context. 206 // 207 // Depending on your protocol or client library language, this is a 208 // map, associative array, symbol table, dictionary, or JSON object 209 // composed of a collection of (MapKey, MapValue) pairs: 210 // 211 // * MapKey type: string 212 // * MapKey value: parameter name 213 // * MapValue type: If parameter's entity type is a composite entity then use 214 // map, otherwise, depending on the parameter value type, it could be one of 215 // string, number, boolean, null, list or map. 216 // * MapValue value: If parameter's entity type is a composite entity then use 217 // map from composite entity property names to property values, otherwise, 218 // use parameter value. 219 google.protobuf.Struct parameters = 3 220 [(google.api.field_behavior) = OPTIONAL]; 221} 222 223// The request message for 224// [Contexts.ListContexts][google.cloud.dialogflow.v2.Contexts.ListContexts]. 225message ListContextsRequest { 226 // Required. The session to list all contexts from. 227 // Format: `projects/<Project ID>/agent/sessions/<Session ID>` or 228 // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User 229 // ID>/sessions/<Session ID>`. 230 // If `Environment ID` is not specified, we assume default 'draft' 231 // environment. If `User ID` is not specified, we assume default '-' user. 232 string parent = 1 [ 233 (google.api.field_behavior) = REQUIRED, 234 (google.api.resource_reference) = { 235 child_type: "dialogflow.googleapis.com/Context" 236 } 237 ]; 238 239 // Optional. The maximum number of items to return in a single page. By 240 // default 100 and at most 1000. 241 int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL]; 242 243 // Optional. The next_page_token value returned from a previous list request. 244 string page_token = 3 [(google.api.field_behavior) = OPTIONAL]; 245} 246 247// The response message for 248// [Contexts.ListContexts][google.cloud.dialogflow.v2.Contexts.ListContexts]. 249message ListContextsResponse { 250 // The list of contexts. There will be a maximum number of items 251 // returned based on the page_size field in the request. 252 repeated Context contexts = 1; 253 254 // Token to retrieve the next page of results, or empty if there are no 255 // more results in the list. 256 string next_page_token = 2; 257} 258 259// The request message for 260// [Contexts.GetContext][google.cloud.dialogflow.v2.Contexts.GetContext]. 261message GetContextRequest { 262 // Required. The name of the context. Format: 263 // `projects/<Project ID>/agent/sessions/<Session ID>/contexts/<Context ID>` 264 // or `projects/<Project ID>/agent/environments/<Environment ID>/users/<User 265 // ID>/sessions/<Session ID>/contexts/<Context ID>`. 266 // If `Environment ID` is not specified, we assume default 'draft' 267 // environment. If `User ID` is not specified, we assume default '-' user. 268 string name = 1 [ 269 (google.api.field_behavior) = REQUIRED, 270 (google.api.resource_reference) = { 271 type: "dialogflow.googleapis.com/Context" 272 } 273 ]; 274} 275 276// The request message for 277// [Contexts.CreateContext][google.cloud.dialogflow.v2.Contexts.CreateContext]. 278message CreateContextRequest { 279 // Required. The session to create a context for. 280 // Format: `projects/<Project ID>/agent/sessions/<Session ID>` or 281 // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User 282 // ID>/sessions/<Session ID>`. 283 // If `Environment ID` is not specified, we assume default 'draft' 284 // environment. If `User ID` is not specified, we assume default '-' user. 285 string parent = 1 [ 286 (google.api.field_behavior) = REQUIRED, 287 (google.api.resource_reference) = { 288 child_type: "dialogflow.googleapis.com/Context" 289 } 290 ]; 291 292 // Required. The context to create. 293 Context context = 2 [(google.api.field_behavior) = REQUIRED]; 294} 295 296// The request message for 297// [Contexts.UpdateContext][google.cloud.dialogflow.v2.Contexts.UpdateContext]. 298message UpdateContextRequest { 299 // Required. The context to update. 300 Context context = 1 [(google.api.field_behavior) = REQUIRED]; 301 302 // Optional. The mask to control which fields get updated. 303 google.protobuf.FieldMask update_mask = 2 304 [(google.api.field_behavior) = OPTIONAL]; 305} 306 307// The request message for 308// [Contexts.DeleteContext][google.cloud.dialogflow.v2.Contexts.DeleteContext]. 309message DeleteContextRequest { 310 // Required. The name of the context to delete. Format: 311 // `projects/<Project ID>/agent/sessions/<Session ID>/contexts/<Context ID>` 312 // or `projects/<Project ID>/agent/environments/<Environment ID>/users/<User 313 // ID>/sessions/<Session ID>/contexts/<Context ID>`. 314 // If `Environment ID` is not specified, we assume default 'draft' 315 // environment. If `User ID` is not specified, we assume default '-' user. 316 string name = 1 [ 317 (google.api.field_behavior) = REQUIRED, 318 (google.api.resource_reference) = { 319 type: "dialogflow.googleapis.com/Context" 320 } 321 ]; 322} 323 324// The request message for 325// [Contexts.DeleteAllContexts][google.cloud.dialogflow.v2.Contexts.DeleteAllContexts]. 326message DeleteAllContextsRequest { 327 // Required. The name of the session to delete all contexts from. Format: 328 // `projects/<Project ID>/agent/sessions/<Session ID>` or `projects/<Project 329 // ID>/agent/environments/<Environment ID>/users/<User ID>/sessions/<Session 330 // ID>`. 331 // If `Environment ID` is not specified we assume default 'draft' environment. 332 // If `User ID` is not specified, we assume default '-' user. 333 string parent = 1 [ 334 (google.api.field_behavior) = REQUIRED, 335 (google.api.resource_reference) = { 336 child_type: "dialogflow.googleapis.com/Context" 337 } 338 ]; 339} 340