webhook.proto 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523
  1. // Copyright 2021 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. syntax = "proto3";
  15. package google.cloud.dialogflow.cx.v3;
  16. import "google/api/annotations.proto";
  17. import "google/api/client.proto";
  18. import "google/api/field_behavior.proto";
  19. import "google/api/resource.proto";
  20. import "google/cloud/dialogflow/cx/v3/response_message.proto";
  21. import "google/protobuf/duration.proto";
  22. import "google/protobuf/empty.proto";
  23. import "google/protobuf/field_mask.proto";
  24. import "google/protobuf/struct.proto";
  25. option cc_enable_arenas = true;
  26. option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3";
  27. option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3;cx";
  28. option java_multiple_files = true;
  29. option java_outer_classname = "WebhookProto";
  30. option java_package = "com.google.cloud.dialogflow.cx.v3";
  31. option objc_class_prefix = "DF";
  32. option (google.api.resource_definition) = {
  33. type: "servicedirectory.googleapis.com/Service"
  34. pattern: "projects/{project}/locations/{location}/namespaces/{namespace}/services/{service}"
  35. };
  36. // Service for managing [Webhooks][google.cloud.dialogflow.cx.v3.Webhook].
  37. service Webhooks {
  38. option (google.api.default_host) = "dialogflow.googleapis.com";
  39. option (google.api.oauth_scopes) =
  40. "https://www.googleapis.com/auth/cloud-platform,"
  41. "https://www.googleapis.com/auth/dialogflow";
  42. // Returns the list of all webhooks in the specified agent.
  43. rpc ListWebhooks(ListWebhooksRequest) returns (ListWebhooksResponse) {
  44. option (google.api.http) = {
  45. get: "/v3/{parent=projects/*/locations/*/agents/*}/webhooks"
  46. };
  47. option (google.api.method_signature) = "parent";
  48. }
  49. // Retrieves the specified webhook.
  50. rpc GetWebhook(GetWebhookRequest) returns (Webhook) {
  51. option (google.api.http) = {
  52. get: "/v3/{name=projects/*/locations/*/agents/*/webhooks/*}"
  53. };
  54. option (google.api.method_signature) = "name";
  55. }
  56. // Creates a webhook in the specified agent.
  57. rpc CreateWebhook(CreateWebhookRequest) returns (Webhook) {
  58. option (google.api.http) = {
  59. post: "/v3/{parent=projects/*/locations/*/agents/*}/webhooks"
  60. body: "webhook"
  61. };
  62. option (google.api.method_signature) = "parent,webhook";
  63. }
  64. // Updates the specified webhook.
  65. rpc UpdateWebhook(UpdateWebhookRequest) returns (Webhook) {
  66. option (google.api.http) = {
  67. patch: "/v3/{webhook.name=projects/*/locations/*/agents/*/webhooks/*}"
  68. body: "webhook"
  69. };
  70. option (google.api.method_signature) = "webhook,update_mask";
  71. }
  72. // Deletes the specified webhook.
  73. rpc DeleteWebhook(DeleteWebhookRequest) returns (google.protobuf.Empty) {
  74. option (google.api.http) = {
  75. delete: "/v3/{name=projects/*/locations/*/agents/*/webhooks/*}"
  76. };
  77. option (google.api.method_signature) = "name";
  78. }
  79. }
  80. // Webhooks host the developer's business logic. During a session, webhooks
  81. // allow the developer to use the data extracted by Dialogflow's natural
  82. // language processing to generate dynamic responses, validate collected data,
  83. // or trigger actions on the backend.
  84. message Webhook {
  85. option (google.api.resource) = {
  86. type: "dialogflow.googleapis.com/Webhook"
  87. pattern: "projects/{project}/locations/{location}/agents/{agent}/webhooks/{webhook}"
  88. };
  89. // Represents configuration for a generic web service.
  90. message GenericWebService {
  91. // Required. The webhook URI for receiving POST requests. It must use https protocol.
  92. string uri = 1 [(google.api.field_behavior) = REQUIRED];
  93. // The user name for HTTP Basic authentication.
  94. string username = 2 [deprecated = true];
  95. // The password for HTTP Basic authentication.
  96. string password = 3 [deprecated = true];
  97. // The HTTP request headers to send together with webhook
  98. // requests.
  99. map<string, string> request_headers = 4;
  100. }
  101. // Represents configuration for a [Service
  102. // Directory](https://cloud.google.com/service-directory) service.
  103. message ServiceDirectoryConfig {
  104. // Required. The name of [Service
  105. // Directory](https://cloud.google.com/service-directory) service.
  106. // Format: `projects/<Project ID>/locations/<Location
  107. // ID>/namespaces/<Namespace ID>/services/<Service ID>`.
  108. // `Location ID` of the service directory must be the same as the location
  109. // of the agent.
  110. string service = 1 [
  111. (google.api.field_behavior) = REQUIRED,
  112. (google.api.resource_reference) = {
  113. type: "servicedirectory.googleapis.com/Service"
  114. }
  115. ];
  116. // Generic Service configuration of this webhook.
  117. GenericWebService generic_web_service = 2;
  118. }
  119. // The unique identifier of the webhook.
  120. // Required for the [Webhooks.UpdateWebhook][google.cloud.dialogflow.cx.v3.Webhooks.UpdateWebhook] method.
  121. // [Webhooks.CreateWebhook][google.cloud.dialogflow.cx.v3.Webhooks.CreateWebhook] populates the name automatically.
  122. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  123. // ID>/webhooks/<Webhook ID>`.
  124. string name = 1;
  125. // Required. The human-readable name of the webhook, unique within the agent.
  126. string display_name = 2 [(google.api.field_behavior) = REQUIRED];
  127. // Required. The webhook configuration.
  128. oneof webhook {
  129. // Configuration for a generic web service.
  130. GenericWebService generic_web_service = 4;
  131. // Configuration for a [Service
  132. // Directory](https://cloud.google.com/service-directory) service.
  133. ServiceDirectoryConfig service_directory = 7;
  134. }
  135. // Webhook execution timeout. Execution is considered failed if Dialogflow
  136. // doesn't receive a response from webhook at the end of the timeout period.
  137. // Defaults to 5 seconds, maximum allowed timeout is 30 seconds.
  138. google.protobuf.Duration timeout = 6;
  139. // Indicates whether the webhook is disabled.
  140. bool disabled = 5;
  141. }
  142. // The request message for [Webhooks.ListWebhooks][google.cloud.dialogflow.cx.v3.Webhooks.ListWebhooks].
  143. message ListWebhooksRequest {
  144. // Required. The agent to list all webhooks for.
  145. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  146. string parent = 1 [
  147. (google.api.field_behavior) = REQUIRED,
  148. (google.api.resource_reference) = {
  149. child_type: "dialogflow.googleapis.com/Webhook"
  150. }
  151. ];
  152. // The maximum number of items to return in a single page. By default 100 and
  153. // at most 1000.
  154. int32 page_size = 2;
  155. // The next_page_token value returned from a previous list request.
  156. string page_token = 3;
  157. }
  158. // The response message for [Webhooks.ListWebhooks][google.cloud.dialogflow.cx.v3.Webhooks.ListWebhooks].
  159. message ListWebhooksResponse {
  160. // The list of webhooks. There will be a maximum number of items returned
  161. // based on the page_size field in the request.
  162. repeated Webhook webhooks = 1;
  163. // Token to retrieve the next page of results, or empty if there are no more
  164. // results in the list.
  165. string next_page_token = 2;
  166. }
  167. // The request message for [Webhooks.GetWebhook][google.cloud.dialogflow.cx.v3.Webhooks.GetWebhook].
  168. message GetWebhookRequest {
  169. // Required. The name of the webhook.
  170. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  171. // ID>/webhooks/<Webhook ID>`.
  172. string name = 1 [
  173. (google.api.field_behavior) = REQUIRED,
  174. (google.api.resource_reference) = {
  175. type: "dialogflow.googleapis.com/Webhook"
  176. }
  177. ];
  178. }
  179. // The request message for [Webhooks.CreateWebhook][google.cloud.dialogflow.cx.v3.Webhooks.CreateWebhook].
  180. message CreateWebhookRequest {
  181. // Required. The agent to create a webhook for.
  182. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  183. string parent = 1 [
  184. (google.api.field_behavior) = REQUIRED,
  185. (google.api.resource_reference) = {
  186. child_type: "dialogflow.googleapis.com/Webhook"
  187. }
  188. ];
  189. // Required. The webhook to create.
  190. Webhook webhook = 2 [(google.api.field_behavior) = REQUIRED];
  191. }
  192. // The request message for [Webhooks.UpdateWebhook][google.cloud.dialogflow.cx.v3.Webhooks.UpdateWebhook].
  193. message UpdateWebhookRequest {
  194. // Required. The webhook to update.
  195. Webhook webhook = 1 [(google.api.field_behavior) = REQUIRED];
  196. // The mask to control which fields get updated. If the mask is not present,
  197. // all fields will be updated.
  198. google.protobuf.FieldMask update_mask = 2;
  199. }
  200. // The request message for [Webhooks.DeleteWebhook][google.cloud.dialogflow.cx.v3.Webhooks.DeleteWebhook].
  201. message DeleteWebhookRequest {
  202. // Required. The name of the webhook to delete.
  203. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  204. // ID>/webhooks/<Webhook ID>`.
  205. string name = 1 [
  206. (google.api.field_behavior) = REQUIRED,
  207. (google.api.resource_reference) = {
  208. type: "dialogflow.googleapis.com/Webhook"
  209. }
  210. ];
  211. // This field has no effect for webhook not being used.
  212. // For webhooks that are used by pages/flows/transition route groups:
  213. //
  214. // * If `force` is set to false, an error will be returned with message
  215. // indicating the referenced resources.
  216. // * If `force` is set to true, Dialogflow will remove the webhook, as well
  217. // as any references to the webhook (i.e. [Webhook][google.cloud.dialogflow.cx.v3.Fulfillment.webhook]
  218. // and [tag][google.cloud.dialogflow.cx.v3.Fulfillment.tag]in fulfillments that point to this webhook
  219. // will be removed).
  220. bool force = 2;
  221. }
  222. // The request message for a webhook call. The request is sent as a JSON object
  223. // and the field names will be presented in camel cases.
  224. message WebhookRequest {
  225. // Represents fulfillment information communicated to the webhook.
  226. message FulfillmentInfo {
  227. // Always present. The tag used to identify which fulfillment is being
  228. // called.
  229. string tag = 1;
  230. }
  231. // Represents intent information communicated to the webhook.
  232. message IntentInfo {
  233. // Represents a value for an intent parameter.
  234. message IntentParameterValue {
  235. // Always present. Original text value extracted from user utterance.
  236. string original_value = 1;
  237. // Always present. Structured value for the parameter extracted from user
  238. // utterance.
  239. google.protobuf.Value resolved_value = 2;
  240. }
  241. // Always present. The unique identifier of the last matched
  242. // [intent][google.cloud.dialogflow.cx.v3.Intent].
  243. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  244. // ID>/intents/<Intent ID>`.
  245. string last_matched_intent = 1 [(google.api.resource_reference) = {
  246. type: "dialogflow.googleapis.com/Intent"
  247. }];
  248. // Always present. The display name of the last matched [intent][google.cloud.dialogflow.cx.v3.Intent].
  249. string display_name = 3;
  250. // Parameters identified as a result of intent matching. This is a map of
  251. // the name of the identified parameter to the value of the parameter
  252. // identified from the user's utterance. All parameters defined in the
  253. // matched intent that are identified will be surfaced here.
  254. map<string, IntentParameterValue> parameters = 2;
  255. // The confidence of the matched intent. Values range from 0.0 (completely
  256. // uncertain) to 1.0 (completely certain).
  257. float confidence = 4;
  258. }
  259. // Represents the result of sentiment analysis.
  260. message SentimentAnalysisResult {
  261. // Sentiment score between -1.0 (negative sentiment) and 1.0 (positive
  262. // sentiment).
  263. float score = 1;
  264. // A non-negative number in the [0, +inf) range, which represents the
  265. // absolute magnitude of sentiment, regardless of score (positive or
  266. // negative).
  267. float magnitude = 2;
  268. }
  269. // Always present. The unique identifier of the [DetectIntentResponse][google.cloud.dialogflow.cx.v3.DetectIntentResponse] that
  270. // will be returned to the API caller.
  271. string detect_intent_response_id = 1;
  272. // The original conversational query.
  273. oneof query {
  274. // If [natural language text][google.cloud.dialogflow.cx.v3.TextInput] was provided as input, this field
  275. // will contain a copy of the text.
  276. string text = 10;
  277. // If an [intent][google.cloud.dialogflow.cx.v3.IntentInput] was provided as input, this field will
  278. // contain a copy of the intent identifier.
  279. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  280. // ID>/intents/<Intent ID>`.
  281. string trigger_intent = 11 [(google.api.resource_reference) = {
  282. type: "dialogflow.googleapis.com/Intent"
  283. }];
  284. // If [natural language speech audio][google.cloud.dialogflow.cx.v3.AudioInput] was provided as input,
  285. // this field will contain the transcript for the audio.
  286. string transcript = 12;
  287. // If an [event][google.cloud.dialogflow.cx.v3.EventInput] was provided as input, this field will contain
  288. // the name of the event.
  289. string trigger_event = 14;
  290. }
  291. // The language code specified in the [original
  292. // request][QueryInput.language_code].
  293. string language_code = 15;
  294. // Always present. Information about the fulfillment that triggered this
  295. // webhook call.
  296. FulfillmentInfo fulfillment_info = 6;
  297. // Information about the last matched intent.
  298. IntentInfo intent_info = 3;
  299. // Information about page status.
  300. PageInfo page_info = 4;
  301. // Information about session status.
  302. SessionInfo session_info = 5;
  303. // The list of rich message responses to present to the user. Webhook can
  304. // choose to append or replace this list in
  305. // [WebhookResponse.fulfillment_response][google.cloud.dialogflow.cx.v3.WebhookResponse.fulfillment_response];
  306. repeated ResponseMessage messages = 7;
  307. // Custom data set in [QueryParameters.payload][google.cloud.dialogflow.cx.v3.QueryParameters.payload].
  308. google.protobuf.Struct payload = 8;
  309. // The sentiment analysis result of the current user request. The field is
  310. // filled when sentiment analysis is configured to be enabled for the request.
  311. SentimentAnalysisResult sentiment_analysis_result = 9;
  312. }
  313. // The response message for a webhook call.
  314. message WebhookResponse {
  315. // Represents a fulfillment response to the user.
  316. message FulfillmentResponse {
  317. // Defines merge behavior for `messages`.
  318. enum MergeBehavior {
  319. // Not specified. `APPEND` will be used.
  320. MERGE_BEHAVIOR_UNSPECIFIED = 0;
  321. // `messages` will be appended to the list of messages waiting to be sent
  322. // to the user.
  323. APPEND = 1;
  324. // `messages` will replace the list of messages waiting to be sent to the
  325. // user.
  326. REPLACE = 2;
  327. }
  328. // The list of rich message responses to present to the user.
  329. repeated ResponseMessage messages = 1;
  330. // Merge behavior for `messages`.
  331. MergeBehavior merge_behavior = 2;
  332. }
  333. // The fulfillment response to send to the user. This field can be omitted by
  334. // the webhook if it does not intend to send any response to the user.
  335. FulfillmentResponse fulfillment_response = 1;
  336. // Information about page status. This field can be omitted by the webhook if
  337. // it does not intend to modify page status.
  338. PageInfo page_info = 2;
  339. // Information about session status. This field can be omitted by the webhook
  340. // if it does not intend to modify session status.
  341. SessionInfo session_info = 3;
  342. // Value to append directly to [QueryResult.webhook_payloads][google.cloud.dialogflow.cx.v3.QueryResult.webhook_payloads].
  343. google.protobuf.Struct payload = 4;
  344. // The target to transition to. This can be set optionally to indicate an
  345. // immediate transition to a different page in the same host flow, or a
  346. // different flow in the same agent.
  347. oneof transition {
  348. // The target page to transition to.
  349. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  350. // ID>/flows/<Flow ID>/pages/<Page ID>`.
  351. string target_page = 5 [(google.api.resource_reference) = {
  352. type: "dialogflow.googleapis.com/Page"
  353. }];
  354. // The target flow to transition to.
  355. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  356. // ID>/flows/<Flow ID>`.
  357. string target_flow = 6 [(google.api.resource_reference) = {
  358. type: "dialogflow.googleapis.com/Flow"
  359. }];
  360. }
  361. }
  362. // Represents page information communicated to and from the webhook.
  363. message PageInfo {
  364. // Represents form information.
  365. message FormInfo {
  366. // Represents parameter information.
  367. message ParameterInfo {
  368. // Represents the state of a parameter.
  369. enum ParameterState {
  370. // Not specified. This value should be never used.
  371. PARAMETER_STATE_UNSPECIFIED = 0;
  372. // Indicates that the parameter does not have a value.
  373. EMPTY = 1;
  374. // Indicates that the parameter value is invalid. This field can be used
  375. // by the webhook to invalidate the parameter and ask the server to
  376. // collect it from the user again.
  377. INVALID = 2;
  378. // Indicates that the parameter has a value.
  379. FILLED = 3;
  380. }
  381. // Always present for [WebhookRequest][google.cloud.dialogflow.cx.v3.WebhookRequest]. Required for
  382. // [WebhookResponse][google.cloud.dialogflow.cx.v3.WebhookResponse].
  383. // The human-readable name of the parameter, unique within the form. This
  384. // field cannot be modified by the webhook.
  385. string display_name = 1;
  386. // Optional for both [WebhookRequest][google.cloud.dialogflow.cx.v3.WebhookRequest] and [WebhookResponse][google.cloud.dialogflow.cx.v3.WebhookResponse].
  387. // Indicates whether the parameter is required. Optional parameters will
  388. // not trigger prompts; however, they are filled if the user specifies
  389. // them. Required parameters must be filled before form filling concludes.
  390. bool required = 2;
  391. // Always present for [WebhookRequest][google.cloud.dialogflow.cx.v3.WebhookRequest]. Required for
  392. // [WebhookResponse][google.cloud.dialogflow.cx.v3.WebhookResponse]. The state of the parameter. This field can be set
  393. // to [INVALID][google.cloud.dialogflow.cx.v3.PageInfo.FormInfo.ParameterInfo.ParameterState.INVALID] by
  394. // the webhook to invalidate the parameter; other values set by the
  395. // webhook will be ignored.
  396. ParameterState state = 3;
  397. // Optional for both [WebhookRequest][google.cloud.dialogflow.cx.v3.WebhookRequest] and [WebhookResponse][google.cloud.dialogflow.cx.v3.WebhookResponse].
  398. // The value of the parameter. This field can be set by the webhook to
  399. // change the parameter value.
  400. google.protobuf.Value value = 4;
  401. // Optional for [WebhookRequest][google.cloud.dialogflow.cx.v3.WebhookRequest]. Ignored for [WebhookResponse][google.cloud.dialogflow.cx.v3.WebhookResponse].
  402. // Indicates if the parameter value was just collected on the last
  403. // conversation turn.
  404. bool just_collected = 5;
  405. }
  406. // Optional for both [WebhookRequest][google.cloud.dialogflow.cx.v3.WebhookRequest] and [WebhookResponse][google.cloud.dialogflow.cx.v3.WebhookResponse].
  407. // The parameters contained in the form. Note that the webhook cannot add
  408. // or remove any form parameter.
  409. repeated ParameterInfo parameter_info = 2;
  410. }
  411. // Always present for [WebhookRequest][google.cloud.dialogflow.cx.v3.WebhookRequest]. Ignored for [WebhookResponse][google.cloud.dialogflow.cx.v3.WebhookResponse].
  412. // The unique identifier of the current page.
  413. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  414. // ID>/flows/<Flow ID>/pages/<Page ID>`.
  415. string current_page = 1 [(google.api.resource_reference) = {
  416. type: "dialogflow.googleapis.com/Page"
  417. }];
  418. // Optional for both [WebhookRequest][google.cloud.dialogflow.cx.v3.WebhookRequest] and [WebhookResponse][google.cloud.dialogflow.cx.v3.WebhookResponse].
  419. // Information about the form.
  420. FormInfo form_info = 3;
  421. }
  422. // Represents session information communicated to and from the webhook.
  423. message SessionInfo {
  424. // Always present for [WebhookRequest][google.cloud.dialogflow.cx.v3.WebhookRequest]. Ignored for [WebhookResponse][google.cloud.dialogflow.cx.v3.WebhookResponse].
  425. // The unique identifier of the [session][google.cloud.dialogflow.cx.v3.DetectIntentRequest.session]. This
  426. // field can be used by the webhook to identify a session.
  427. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  428. // ID>/sessions/<Session ID>` or `projects/<Project ID>/locations/<Location
  429. // ID>/agents/<Agent ID>/environments/<Environment ID>/sessions/<Session ID>`
  430. // if environment is specified.
  431. string session = 1 [(google.api.resource_reference) = {
  432. type: "dialogflow.googleapis.com/Session"
  433. }];
  434. // Optional for [WebhookRequest][google.cloud.dialogflow.cx.v3.WebhookRequest]. Optional for [WebhookResponse][google.cloud.dialogflow.cx.v3.WebhookResponse].
  435. // All parameters collected from forms and intents during the session.
  436. // Parameters can be created, updated, or removed by the webhook. To remove a
  437. // parameter from the session, the webhook should explicitly set the parameter
  438. // value to null in [WebhookResponse][google.cloud.dialogflow.cx.v3.WebhookResponse]. The map is keyed by parameters'
  439. // display names.
  440. map<string, google.protobuf.Value> parameters = 2;
  441. }