googleapis/google/cloud/dialogflow/cx/v3beta1/intent.proto

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.dialogflow.cx.v3beta1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3Beta1";
option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3beta1;cx";
option java_multiple_files = true;
option java_outer_classname = "IntentProto";
option java_package = "com.google.cloud.dialogflow.cx.v3beta1";
option objc_class_prefix = "DF";

// Service for managing [Intents][google.cloud.dialogflow.cx.v3beta1.Intent].
service Intents {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/dialogflow";

  // Returns the list of all intents in the specified agent.
  rpc ListIntents(ListIntentsRequest) returns (ListIntentsResponse) {
    option (google.api.http) = {
      get: "/v3beta1/{parent=projects/*/locations/*/agents/*}/intents"
    };
    option (google.api.method_signature) = "parent";
  }

  // Retrieves the specified intent.
  rpc GetIntent(GetIntentRequest) returns (Intent) {
    option (google.api.http) = {
      get: "/v3beta1/{name=projects/*/locations/*/agents/*/intents/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Creates an intent in the specified agent.
  rpc CreateIntent(CreateIntentRequest) returns (Intent) {
    option (google.api.http) = {
      post: "/v3beta1/{parent=projects/*/locations/*/agents/*}/intents"
      body: "intent"
    };
    option (google.api.method_signature) = "parent,intent";
  }

  // Updates the specified intent.
  rpc UpdateIntent(UpdateIntentRequest) returns (Intent) {
    option (google.api.http) = {
      patch: "/v3beta1/{intent.name=projects/*/locations/*/agents/*/intents/*}"
      body: "intent"
    };
    option (google.api.method_signature) = "intent,update_mask";
  }

  // Deletes the specified intent.
  rpc DeleteIntent(DeleteIntentRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v3beta1/{name=projects/*/locations/*/agents/*/intents/*}"
    };
    option (google.api.method_signature) = "name";
  }
}

// An intent represents a user's intent to interact with a conversational agent.
//
// You can provide information for the Dialogflow API to use to match user input
// to an intent by adding training phrases (i.e., examples of user input) to
// your intent.
message Intent {
  option (google.api.resource) = {
    type: "dialogflow.googleapis.com/Intent"
    pattern: "projects/{project}/locations/{location}/agents/{agent}/intents/{intent}"
  };

  // Represents an example that the agent is trained on to identify the intent.
  message TrainingPhrase {
    // Represents a part of a training phrase.
    message Part {
      // Required. The text for this part.
      string text = 1 [(google.api.field_behavior) = REQUIRED];

      // The [parameter][google.cloud.dialogflow.cx.v3beta1.Intent.Parameter] used to annotate this part of the
      // training phrase. This field is required for annotated parts of the
      // training phrase.
      string parameter_id = 2;
    }

    // Output only. The unique identifier of the training phrase.
    string id = 1;

    // Required. The ordered list of training phrase parts.
    // The parts are concatenated in order to form the training phrase.
    //
    // Note: The API does not automatically annotate training phrases like the
    // Dialogflow Console does.
    //
    // Note: Do not forget to include whitespace at part boundaries, so the
    // training phrase is well formatted when the parts are concatenated.
    //
    // If the training phrase does not need to be annotated with parameters,
    // you just need a single part with only the [Part.text][google.cloud.dialogflow.cx.v3beta1.Intent.TrainingPhrase.Part.text] field set.
    //
    // If you want to annotate the training phrase, you must create multiple
    // parts, where the fields of each part are populated in one of two ways:
    //
    // -   `Part.text` is set to a part of the phrase that has no parameters.
    // -   `Part.text` is set to a part of the phrase that you want to annotate,
    //     and the `parameter_id` field is set.
    repeated Part parts = 2 [(google.api.field_behavior) = REQUIRED];

    // Indicates how many times this example was added to the intent.
    int32 repeat_count = 3;
  }

  // Represents an intent parameter.
  message Parameter {
    // Required. The unique identifier of the parameter. This field
    // is used by [training phrases][google.cloud.dialogflow.cx.v3beta1.Intent.TrainingPhrase] to annotate their
    // [parts][google.cloud.dialogflow.cx.v3beta1.Intent.TrainingPhrase.Part].
    string id = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. The entity type of the parameter.
    // Format: `projects/-/locations/-/agents/-/entityTypes/<System Entity Type
    // ID>` for system entity types (for example,
    // `projects/-/locations/-/agents/-/entityTypes/sys.date`), or
    // `projects/<Project ID>/locations/<Location ID>/agents/<Agent
    // ID>/entityTypes/<Entity Type ID>` for developer entity types.
    string entity_type = 2 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {
        type: "dialogflow.googleapis.com/EntityType"
      }
    ];

    // Indicates whether the parameter represents a list of values.
    bool is_list = 3;

    // Indicates whether the parameter content should be redacted in text and
    // audio. If the flag is set to true, the parameter content will be replaced
    // by parameter name in both request and response.
    // Note: the parameter content is subject to redaction if either parameter
    // level redaction or [entity type level redaction][google.cloud.dialogflow.cx.v3beta1.EntityType.redact] is
    // enabled.
    bool redact = 4;
  }

  // The unique identifier of the intent.
  // Required for the [Intents.UpdateIntent][google.cloud.dialogflow.cx.v3beta1.Intents.UpdateIntent] method. [Intents.CreateIntent][google.cloud.dialogflow.cx.v3beta1.Intents.CreateIntent]
  // populates the name automatically.
  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  // ID>/intents/<Intent ID>`.
  string name = 1;

  // Required. The human-readable name of the intent, unique within the agent.
  string display_name = 2 [(google.api.field_behavior) = REQUIRED];

  // The collection of training phrases the agent is trained on to identify the
  // intent.
  repeated TrainingPhrase training_phrases = 3;

  // The collection of parameters associated with the intent.
  repeated Parameter parameters = 4;

  // The priority of this intent. Higher numbers represent higher
  // priorities.
  //
  // - If the supplied value is unspecified or 0, the service
  //   translates the value to 500,000, which corresponds to the
  //   `Normal` priority in the console.
  // - If the supplied value is negative, the intent is ignored
  //   in runtime detect intent requests.
  int32 priority = 5;

  // Indicates whether this is a fallback intent. Currently only default
  // fallback intent is allowed in the agent, which is added upon agent
  // creation.
  // Adding training phrases to fallback intent is useful in the case of
  // requests that are mistakenly matched, since training phrases assigned to
  // fallback intents act as negative examples that triggers no-match event.
  bool is_fallback = 6;

  // Optional. The key/value metadata to label an intent. Labels can contain
  // lowercase letters, digits and the symbols '-' and '_'. International
  // characters are allowed, including letters from unicase alphabets. Keys must
  // start with a letter. Keys and values can be no longer than 63 characters
  // and no more than 128 bytes.
  //
  // Prefix "sys-" is reserved for Dialogflow defined labels. Currently allowed
  // Dialogflow defined labels include:
  // * sys-head
  // * sys-contextual
  // The above labels do not require value. "sys-head" means the intent is a
  // head intent. "sys-contextual" means the intent is a contextual intent.
  map<string, string> labels = 7 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Human readable description for better understanding an intent like its
  // scope, content, result etc. Maximum character limit: 140 characters.
  string description = 8 [(google.api.field_behavior) = OPTIONAL];
}

// The request message for [Intents.ListIntents][google.cloud.dialogflow.cx.v3beta1.Intents.ListIntents].
message ListIntentsRequest {
  // Required. The agent to list all intents for.
  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/Intent"
    }
  ];

  // The language to list intents for. The following fields are language
  // dependent:
  //
  // *   `Intent.training_phrases.parts.text`
  //
  // If not specified, the agent's default language is used.
  // [Many
  // languages](https://cloud.google.com/dialogflow/docs/reference/language)
  // are supported.
  // Note: languages must be enabled in the agent before they can be used.
  string language_code = 2;

  // The resource view to apply to the returned intent.
  IntentView intent_view = 5;

  // The maximum number of items to return in a single page. By default 100 and
  // at most 1000.
  int32 page_size = 3;

  // The next_page_token value returned from a previous list request.
  string page_token = 4;
}

// The response message for [Intents.ListIntents][google.cloud.dialogflow.cx.v3beta1.Intents.ListIntents].
message ListIntentsResponse {
  // The list of intents. There will be a maximum number of items returned based
  // on the page_size field in the request.
  repeated Intent intents = 1;

  // Token to retrieve the next page of results, or empty if there are no more
  // results in the list.
  string next_page_token = 2;
}

// The request message for [Intents.GetIntent][google.cloud.dialogflow.cx.v3beta1.Intents.GetIntent].
message GetIntentRequest {
  // Required. The name of the intent.
  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  // ID>/intents/<Intent ID>`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/Intent"
    }
  ];

  // The language to retrieve the intent for. The following fields are language
  // dependent:
  //
  // *   `Intent.training_phrases.parts.text`
  //
  // If not specified, the agent's default language is used.
  // [Many
  // languages](https://cloud.google.com/dialogflow/docs/reference/language)
  // are supported.
  // Note: languages must be enabled in the agent before they can be used.
  string language_code = 2;
}

// The request message for [Intents.CreateIntent][google.cloud.dialogflow.cx.v3beta1.Intents.CreateIntent].
message CreateIntentRequest {
  // Required. The agent to create an intent for.
  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/Intent"
    }
  ];

  // Required. The intent to create.
  Intent intent = 2 [(google.api.field_behavior) = REQUIRED];

  // The language of the following fields in `intent`:
  //
  // *   `Intent.training_phrases.parts.text`
  //
  // If not specified, the agent's default language is used.
  // [Many
  // languages](https://cloud.google.com/dialogflow/docs/reference/language)
  // are supported.
  // Note: languages must be enabled in the agent before they can be used.
  string language_code = 3;
}

// The request message for [Intents.UpdateIntent][google.cloud.dialogflow.cx.v3beta1.Intents.UpdateIntent].
message UpdateIntentRequest {
  // Required. The intent to update.
  Intent intent = 1 [(google.api.field_behavior) = REQUIRED];

  // The language of the following fields in `intent`:
  //
  // *   `Intent.training_phrases.parts.text`
  //
  // If not specified, the agent's default language is used.
  // [Many
  // languages](https://cloud.google.com/dialogflow/docs/reference/language)
  // are supported.
  // Note: languages must be enabled in the agent before they can be used.
  string language_code = 2;

  // The mask to control which fields get updated. If the mask is not present,
  // all fields will be updated.
  google.protobuf.FieldMask update_mask = 3;
}

// The request message for [Intents.DeleteIntent][google.cloud.dialogflow.cx.v3beta1.Intents.DeleteIntent].
message DeleteIntentRequest {
  // Required. The name of the intent to delete.
  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  // ID>/intents/<Intent ID>`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/Intent"
    }
  ];
}

// Represents the options for views of an intent.
// An intent can be a sizable object. Therefore, we provide a resource view that
// does not return training phrases in the response.
enum IntentView {
  // Not specified. Treated as INTENT_VIEW_FULL.
  INTENT_VIEW_UNSPECIFIED = 0;

  // Training phrases field is not populated in the response.
  INTENT_VIEW_PARTIAL = 1;

  // All fields are populated.
  INTENT_VIEW_FULL = 2;
}