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:
214  //     -   If parameter's entity type is a composite entity: map
215  //     -   Else: depending on parameter value type, could be one of string,
216  //         number, boolean, null, list or map
217  // -   MapValue value:
218  //     -   If parameter's entity type is a composite entity:
219  //         map from composite entity property names to property values
220  //     -   Else: parameter value
221  google.protobuf.Struct parameters = 3
222      [(google.api.field_behavior) = OPTIONAL];
223}
224
225// The request message for
226// [Contexts.ListContexts][google.cloud.dialogflow.v2.Contexts.ListContexts].
227message ListContextsRequest {
228  // Required. The session to list all contexts from.
229  // Format: `projects/<Project ID>/agent/sessions/<Session ID>` or
230  // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User
231  // ID>/sessions/<Session ID>`.
232  // If `Environment ID` is not specified, we assume default 'draft'
233  // environment. If `User ID` is not specified, we assume default '-' user.
234  string parent = 1 [
235    (google.api.field_behavior) = REQUIRED,
236    (google.api.resource_reference) = {
237      child_type: "dialogflow.googleapis.com/Context"
238    }
239  ];
240
241  // Optional. The maximum number of items to return in a single page. By
242  // default 100 and at most 1000.
243  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
244
245  // Optional. The next_page_token value returned from a previous list request.
246  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
247}
248
249// The response message for
250// [Contexts.ListContexts][google.cloud.dialogflow.v2.Contexts.ListContexts].
251message ListContextsResponse {
252  // The list of contexts. There will be a maximum number of items
253  // returned based on the page_size field in the request.
254  repeated Context contexts = 1;
255
256  // Token to retrieve the next page of results, or empty if there are no
257  // more results in the list.
258  string next_page_token = 2;
259}
260
261// The request message for
262// [Contexts.GetContext][google.cloud.dialogflow.v2.Contexts.GetContext].
263message GetContextRequest {
264  // Required. The name of the context. Format:
265  // `projects/<Project ID>/agent/sessions/<Session ID>/contexts/<Context ID>`
266  // or `projects/<Project ID>/agent/environments/<Environment ID>/users/<User
267  // ID>/sessions/<Session ID>/contexts/<Context ID>`.
268  // If `Environment ID` is not specified, we assume default 'draft'
269  // environment. If `User ID` is not specified, we assume default '-' user.
270  string name = 1 [
271    (google.api.field_behavior) = REQUIRED,
272    (google.api.resource_reference) = {
273      type: "dialogflow.googleapis.com/Context"
274    }
275  ];
276}
277
278// The request message for
279// [Contexts.CreateContext][google.cloud.dialogflow.v2.Contexts.CreateContext].
280message CreateContextRequest {
281  // Required. The session to create a context for.
282  // Format: `projects/<Project ID>/agent/sessions/<Session ID>` or
283  // `projects/<Project ID>/agent/environments/<Environment ID>/users/<User
284  // ID>/sessions/<Session ID>`.
285  // If `Environment ID` is not specified, we assume default 'draft'
286  // environment. If `User ID` is not specified, we assume default '-' user.
287  string parent = 1 [
288    (google.api.field_behavior) = REQUIRED,
289    (google.api.resource_reference) = {
290      child_type: "dialogflow.googleapis.com/Context"
291    }
292  ];
293
294  // Required. The context to create.
295  Context context = 2 [(google.api.field_behavior) = REQUIRED];
296}
297
298// The request message for
299// [Contexts.UpdateContext][google.cloud.dialogflow.v2.Contexts.UpdateContext].
300message UpdateContextRequest {
301  // Required. The context to update.
302  Context context = 1 [(google.api.field_behavior) = REQUIRED];
303
304  // Optional. The mask to control which fields get updated.
305  google.protobuf.FieldMask update_mask = 2
306      [(google.api.field_behavior) = OPTIONAL];
307}
308
309// The request message for
310// [Contexts.DeleteContext][google.cloud.dialogflow.v2.Contexts.DeleteContext].
311message DeleteContextRequest {
312  // Required. The name of the context to delete. Format:
313  // `projects/<Project ID>/agent/sessions/<Session ID>/contexts/<Context ID>`
314  // or `projects/<Project ID>/agent/environments/<Environment ID>/users/<User
315  // ID>/sessions/<Session ID>/contexts/<Context ID>`.
316  // If `Environment ID` is not specified, we assume default 'draft'
317  // environment. If `User ID` is not specified, we assume default '-' user.
318  string name = 1 [
319    (google.api.field_behavior) = REQUIRED,
320    (google.api.resource_reference) = {
321      type: "dialogflow.googleapis.com/Context"
322    }
323  ];
324}
325
326// The request message for
327// [Contexts.DeleteAllContexts][google.cloud.dialogflow.v2.Contexts.DeleteAllContexts].
328message DeleteAllContextsRequest {
329  // Required. The name of the session to delete all contexts from. Format:
330  // `projects/<Project ID>/agent/sessions/<Session ID>` or `projects/<Project
331  // ID>/agent/environments/<Environment ID>/users/<User ID>/sessions/<Session
332  // ID>`.
333  // If `Environment ID` is not specified we assume default 'draft' environment.
334  // If `User ID` is not specified, we assume default '-' user.
335  string parent = 1 [
336    (google.api.field_behavior) = REQUIRED,
337    (google.api.resource_reference) = {
338      child_type: "dialogflow.googleapis.com/Context"
339    }
340  ];
341}
342